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Editor’s  Preface 


So  much  code. 

This  was  the  year  in  which  Dr.  Dobb’s  Journal  published  the  conclusion  to  Jim 
Hendrix’s  Small-C  Version  2,  one  of  the  most  popular  articles  ever  to  appear  in  the 
magazine.  “Article”  is  the  wrong  word,  of  course,  a  remnant  of  another  age  of 
publishing.  Dr.  Dobb’s  was  one  of  the  publications  that  brought  in  the  odd  new  era  in 
which  magazine  pages  were  packed  with  articles,  whole  volumes,  written  in  no  human 
language.  Small-C  Version  2  is  a  piece  of  software,  and  a  very  useful  one.  By 
publishing  it  in  source-code  form,  Dr.  Dobb’s  made  the  C  programming  language 
available  to  thousands  of  programmers  who  would  not  otherwise  have  been  able  to 
learn  how  to  use  it,  let  alone  learn  how  the  language  was  constructed. 

Dr.  Dobb’s  published  a  lot  of  source  code  in  1983;  that’s  what  the  magazine  was, 
and  is,  all  about.  In  later  years  some  of  the  code  would  also  be  distributed  via  more 
modern  media  that  print  electronically  and  on  disk.  The  latest  version  of  Small-C 
would  be  one  of  the  first  pieces  of  disk  software  from  Dr.  Dobb’s.  But  back  in  1983, 
it  was  all  software  on  paper,  and  there  was  indeed  a  lot  of  it,  as  the  size  of  this 
volume  attests. 

In  this  volume  you  will  find  all  the  software  (as  well  as  some  more  conventional 
articles)  published  in  Dr.  Dobb’s  Journal  in  1983.  There’s  Ed  Ream’s  RED  editor, 
written  in  Small-C,  and  Augusta,  the  microcomputer  implementation  of  a  subset  of  the 
Ada  language.  You’ll  find  clever  algorithms  for  implementing  co-routines,  fast  matrix 
operations,  divisibility  tests,  B-Tree  ISAM  techniques.  Dr.  Dobb’s  scope  has  always 
been  broad,  so  you’ll  find  articles  herein  that  include  code  for  the  6800,  6502,  8080, 
Z80,  8086  and  68000  microprocessors;  high-level  code  in  Forth,  C,  Basic,  Ada,  Pascal, 
and  some  languages  created  for  the  occasion.  You’ll  also  find  letters  to  the  editor, 
opinionated  columnists,  running  dialog  on  the  craft  of  software  development. 

The  point  of  it  all  is  this:  good  programmers  can  learn  from  others’  code.  Despite 
the  very  real  usefulness  of  the  code  published  in  Dr.  Dobb’s  Journal ,  the  code’s 
greatest  value  is  in  its  tutorial  aspect.  That’s  why  it  still  makes  sense  to  release  it  in  so 
archaic  a  medium  as  this  volume. 


Michael  Swaine,  Editor 
Dr.  Dobb  ’s  Journal 
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Split  Decision 

Dear  Mr.  Harrison: 

I  have  a  software  “need”  I  would 
also  like  to  lay  out  to  you  and  potential 
readers.  There  appear  to  be  inherent  ad¬ 
vantages  to  using  the  CRT  as  something 
more  than  a  tunnel  into  one  corner  of 
the  computer’s  “output  buffer.”  In  fact, 
there  seems  no  reason  why  programmers 
would  not  reap  immense  benefit  from  the 
flexibility  to  define  alternative  “win¬ 
dows”  into  various  portions  of  memory 
and  disk  storage.  Larger  computers  and 
operating  systems  and  related  software 
are  presently  making  available  (mostly 
through  graphic  software  innovations 
designed  a  decade  ago  but  only  now 
generally  implemented)  multiple-window 
displays.  An  excellent  model  for  this  is 
Smalltalk  and  Xerox  Altos’  and  Star’s 
multi- window  environment.  The  Corvus 
Concept  (limited  in  other  respects)  has 
had  its  word  processing  software  designed 
for  multiple  views  of  different  (or  same) 
documents.  Several  software  items  (i.e., 
word  processors  like  Mince  and  its 
copy  Perfect  Writer)  allow  split-screen 
display  as  does  a  file  comparator  utility 
by  Leor  Zolman.  But  these  are  all  partial 
implementations  outside  of  a  larger  oper¬ 
ating  system  environment  within  which 
the  user  should  have  the  ability  to  choose 
single  or  multiple  displays.  Such  displays 
would  enable  the  user  to  view  the  (static) 
contents  of  files  while  writing  modules 
from  them  into  a  currently  edited  pro¬ 
gram  file  on  a  second  window.  With  even 
split  screen,  file  comparisons  or  the  abili¬ 
ty  to  monitor  program  compilation  while 
editing  other  files  or  even  running  a  pro¬ 
gram  could  be  accomplished.  To  keep  it 
simple  for  a  CP/M  environment,  in  a 
split-screen  environment,  one  screen 
could  always  be  inert  while  the  other  is 
“active,”  and  still  provide  significant 
information  enhancement. 

I  am  only  a  beginner  in  this  age  of 
micros  and  software,  and  so  still  tremble 
at  the  thought  of  re-tooling  the  BIOS 
or  other  innards  of  an  OS  or  display  inter¬ 
face,  yet  feel  a  bit  puzzled  at  why  others 
have  not  seen  merit  in  this  approach,  at 
least  to  offer  at  the  OS  level  a  choice  of 
whether  or  not  to  opt  for  single,  full¬ 
screen  display  or  for  two  or  more  screens 
(partitions  of  the  full  screen)  within 
which  different  files  or  operations  can  be 
loaded.  If  Mince  can  do  it,  why  can’t  the 
OS?  Have  you  any  leads  as  to  program¬ 
mers  who  have  gone  after  this  generalized 
kind  of  utility? 


I  find  DDJ  most  welcome  in  terms 
of  its  serious  and  technical  approach  to 
micros  and  software  development.  I  shall 
stay  tuned. 

Sincerely, 

Andrew  N.  White 
22 11 -A  Mohala  Way 
Honolulu,  Hawaii  96822 

Sole -Saving  Subscription 

Dear  Doctor  Dobb, 

I’m  sick  of  walking  to  the  news¬ 
stand  to  find  that  your  magazine  has  been 
sold  out.  Please  enter  me  on  your  sub¬ 
scription  list.  Enclosed  is  a  money  order 
for  $25.00. 

Thank  you  for  an  enjoyable  and  in¬ 
formative  magazine. 

Sincerely  yours, 

William  C.  DuPree 
511  Clyde,  Apt.  30 
Calumet  City,  IL  60409 

We  are  working  on  this.  Perhaps  we 
should  merge  with  High  Times.  I  didn’t 
know  there  were  any  newsstands  in 
Calumet  City  carrying  DDJ,  but  take 
heed,  the  subscription  route  is  the  “path 
of  choice.  ”  —  Ed. 

A  Dis-Contented  Reader 

Dear  Hank: 

When  DDJ  and  BYTE  (and,  to  a 
lesser  degree,  Kilobaud)  started,  I  found 
most  of  the  content  informative  and 
stimulating.  Now,  for  the  last  two  years 
or  so,  BYTE  has  had  (on  the  average) 
only  one  article  of  sufficient  technical 
content  and  level  to  justify  the  time  to 
read  it,  per  month.  DDJ  (alas!)  is,  in  my 
opinion,  down  to  one  per  year. 

Thanks  for  being  at  the  front  of  the 
micro  revolution.  I’m  really  sorry  your 
editorial  policy  has  not  attracted  more 
good  content  that  educates  rather  than 
gives  low-level  listings  of  yet  another 
assembler  or  monitor.  I  have  nothing 
against  listings  —  they  are  often  neces¬ 
sary  -  but  they  are  not  very  informative 
as  such.  Perhaps  tables  and  figures  fo¬ 
cused  on  program  variables,  algorithms, 
and  flow  charts  would  be  more  helpful. 
Tom  Pittman 
San  Jose,  CA 

Computer  as  Salesperson  ? 

Dear  Hank: 

The  following  idea  might,  for  all  I 
know,  already  be  in  application  in  the 
U  S.  networks.  (Here  in  New  Zealand 


a  government  sales  tax  of  40%  has  stran¬ 
gled  growth  of  personal  computers.) 

Commercial  networks  could  be  used 
for  a  “try  before  you  buy”  preview  of 
software.  Because  of  slow  baud  rates, 
interactive  responses  would  be  limited; 
that  is,  graphics  games  would  be  demon¬ 
strated  as  snapshots  of  how  the  screen 
looks.  Data  manipulation  programs  like 
accounting  programs  and  even  editors 
could  be  demonstrated  —  albeit  slowly 
—  in  real  time.  There  would  be  some  sort 
of  hourly  charge  for  use.  Thus,  you  could 
try  a  program  for  a  while  without  neces¬ 
sarily  buying  it. 

Only  after  you  decided  to  purchase 
the  software,  and  gave  the  system  your 
order  code  and  password,  would  the 
program  be  either  down-loaded  into  your 
computer  or  else  sent  on  magnetic 
media  via  post.  To  the  extent  that  this 
would  make  acquiring  software  easier 
than  going  to  a  friend’s  house,  it  would 
reduce  software  piracy. 

There  would  not  be  any  real  prob¬ 
lem  in  restricting  these  demonstrations  to 
any  given  computer,  and  in  fact,  this 
mass -marketing  approach  could  greatly 
increase  software  availability  for  people 
with  oddball  machines  spread  thinly 
around  the  population  base. 

The  early  concept  of  using  a  network 
to  access  a  big,  powerful  computer  is  out 
of  date,  as  personal  computers  become 
more  powerful.  My  proposal  is  that  the 
large  computer  act  as  a  salesman. 

Cordially  yours, 

Jay  D.  Mann 
330  Centaurus  Road 
Christchurch  2 
New  Zealand 

Why  Pascal  at  All? 

Dear  Doctor  Dobb, 

The  cheapie  JRT  system  is  really  use¬ 
less  because  it  doesn’t  know  how  to  do 
arithmetic!  There  are  at  least  three  prob¬ 
lems  with  its  “real”  number  arithmetic 
in  addition  to  its  compiler  bugs. 

When  finite-register  machines  try  to 
approximate  the  real  number  continuum, 
they  tend  to  fail  as  the  numbers  approach 
zero.  When  the  absolute  value  of  the 
number  is  less  than  the  minimum  allowed 
in  the  representation,  the  stored  result 
should  be  identically  equal  to  zero.  Per¬ 
haps  the  implementers  of  JRT  Pascal 
never  learned  this  in  school. 

There  is  one  more  arithmetic  bug 
that  makes  the  system  useless  foraccount- 
(Continued  on  page  12) 
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EDITORIAL 


High-Tech  Writer 


Hello:  My  name  is  Hank  Harrison.  As  a  long-time 
reader  and  now  the  new  Editor  of  Dr.  Dobb’s  Journal  I’m 
convinced  that  Dr.  Dobb’s  is  the  finest  small  publication  in 
the  world  for  the  microcomputer  community.  It  is  good, 
not  because  it  is  engorged  with  advertisements,  not  because 
it  appeals  to  the  hobbyist,  or  is  mistake  free,  but  because, 
since  1976,  Dr.  Dobb’s  has  been  read  and  respected  by  the 
real  pioneers  and  inventors  of  our  trade  .  .  .  the  Gyro  Gear- 
loose  computerists. 

For  many  issues  past.  Marlin  Ouverson  has  been  sitting 
in  this  chair  and  running  Dr.  Dobb’s  well.  I  have  no  inten¬ 
tion  of  changing  his  good  works.  I  think,  however,  that 
since  I  grew  up  in  a  tough  town,  Hayward,  CA,  and  have 
just  returned  from  two  years  in  Dublin,  Ireland,  lecturing 
in  Industrial  Psychology  at  Trinity  College  and  looking  for 
Celtic  artifacts,  I  will  have  to  be  slightly  different  —  not 
radically  different,  but,  well,  just  Plain  Vanilla  me.  For  the 
past  two  decades  I  have  earned  a  sporadic  living  as  a  tech 
writer. 

*  *  * 

Recently  Dr.  Dobb’s  lost  a  greatly  needed  bunch  of 
money  by  taking  an  ethical  stand  with  an  advertiser.  Two 
of  our  top  experts  said  the  product  didn’t  work  and  wasn’t 
worth  the  very  low  price  advertised.  The  owner  of  the 
company  wrote  back  and  claimed  he  was  disgusted,  then 
another  letter  appeared  in  another  well-respected  weekly 
journal  confirming  our  research,  then  we  received  other 
letters,  quite  independently  and  without  solicitation,  also 
claiming  the  product  is  awkward  and  unreliable,  and  won¬ 
dering  how  it  could  have  received  such  a  good  rating  from 
the  well-respected  weekly  news  magazine.  The  advertiser 
who  claims  to  have  been  disgusted,  asserts  that  three  other 
magazines  of  great  reknown  paid  homage  to  his  product 
and  why  shouldn’t  we? 

About  a  week  later,  we  received  a  very  well  written  ar¬ 
ticle  claiming  that  the  product  is  flawed  but  fabulous.  This 
long  piece  was  written,  not  by  a  homebrew  person,  but  by  a 
professional  with  a  lot  of  experience  with  similar  products. 
He  claims  the  product  remains  unfriendly,  but  is  no  more 
or  less  unfriendly  than  other  similar  products  costing  ten 
times  as  much.  I  checked  on  this  claim,  and  reread  the  two 
reviews  in  the  other  magazines.  Neither  was  a  rave  as  the 
advertiser  had  claimed,  but  they  were  still  positive  reviews. 
I  then  went  to  our  old  files  and  located  certain  press  re¬ 
leases.  Guess  what?  Many  elements  of  the  PR  material  ap¬ 
peared  in  the  two  favorable  reviews.  Then  the  entire  issue 
took  on  a  new  dimension.  The  next  day,  one  of  our  own 
readers  wrote  in  to  tell  us  that  she  hasn’t  had  a  chance  to 
use  the  product  because  it  just  never  arrived  in  the  mail. 

I’d  like  to  mention  the  fact  that  DDJ  takes  the  time  to 
“handle”  the  software  and  hardware  we  feature  and  we  try 
to  let  the  reader  draw  his  or  her  own  conclusions. 

*  *  * 


In  going  over  the  past  issues  of  Dr.  Dobb’s,  I  noticed  an 
amazing  dearth  of  women  contributors.  I  realize  that  this  is 
traceable  to  the  education  system  and  an  industry-wide 
bias.  I  also  realize  that  women  in  the  systems  development 
area  may  be  too  busy  to  send  in  articles  to  DDJ,  but  I  can 
safely  say  we  are  looking  for  articles  by  women,  simply  to 
balance  things  out  and  also  to  honor  an  old  obligation  of 
mine  —  I  think  it  would  be  good  for  the  industry. 

Another  point  must  also  be  considered,  having  to  do 
with  a  controversial  suit  being  brought  against  a  small  game 
manufacturer  for  releasing  an  odious  little  game  wherein 
General  Custer,  true  to  his  reputation,  rapes  an  Indian 
maiden  until  shot  with  an  arrow.  This  offense  is  not  as  por¬ 
nographic  as  Women  Against  Pornography  depict  it,  nor  is 
it  a  simple  affront  to  women,  per  se,  since  all  acts  of  rape 
are  an  affront  to  both  genders  and  a  few  in  between.  This 
Wild  West  maze  game  is  a  distortion  of  history  and  an  af¬ 
front  to  Native  Americans  because  they  won  the  battle 
with  Custer  the  first  time.  The  massacre  isn’t  reflected  in  the 
game.  This  kind  of  tripe  is  an  assault  on  the  ethics  of  the 
entire  microcomputer  industry.  Is  Willy  Loman  moving  in? 

How  is  it  possible  that  some  really  ugly  people  were 
allowed  to  produce  such  a  game  in  the  first  place?  Is  the 
First  Amendment  at  risk  here?  You  can’t  tell  me  someone 
with  authority  didn’t  see  this  one  coming.  Have  we  slipped 
this  far?  Who  wrote  the  program?  How  many  people  saw 
the  game  under  development  and  said  nothing?  “Hmmm, 
things  are  getting  curiouser  and  curiouser,”  said  Alice  (in 
Wonderland). 

*  *  * 

Last  week  I  received  a  call  from  the  most  famous  board 
game  manufacturer  in  existence.  They  were  looking  for  a 
back  issue  of  Dr.  Dobb’s  that  detailed  their  game,  in  soft¬ 
ware.  Apparently  they  want  to  computerize  the  game  for 
international  release.  They  stand  to  make  a  fortune.  The 
guy  that  blissfully  wrote  that  old  program  won’t  get  a 
penny.  He  put  it  in  public  domain  and  listed  the  code  in 
Dr.  Dobb’s. 

We  at  Dobb’s  have  long  been  thought  of  as  consumer 
advocates.  We  will  therefore  be  running  more  Dobb’s  Ex 
Machina  as  the  time  goes  on.  In  that  context,  we  will  be 
emphasizing  the  legal  ramifications  of  the  public  domain 
software  issue.  So  if  you’re  looking  for  changes,  look  for 
them  in  terms  of  an  intensification  of  our  traditional  ethics. 
Remember,  Willy  Loman  is  lurking  in  the  wings,  and  he 
can’t  program,  and  if  you  don’t  know  who  Willy  Loman  is, 
ask  the  ghost  of  Marilyn  Monroe. 

Hank  Harrison 
Senior  Editor 
Dr.  Dobb ’s  Journal 
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16-BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


Recent  Software,  Briefly  Reviewed 
DOSCPM,  by  Adaptive  Computer 
Systems,  P.  O.  Box  280B,  Wheeling,  IL 
60090.  $50.  An  efficient  and  compact 
utility  to  convert  PC-DOS  disk  files  to 
CP/M-86  format.  It’s  easy  to  use,  very 
reliable,  and  has  excellent  error  han¬ 
dling.  The  six  pages  of  documentation 
fit  nicely  into  the  CP/M-86  operator’s 
manual.  It  has  two  minor  drawbacks: 
it  only  copies  files  one  direction  (does 
not  convert  CP/M-86  files  to  PC-DOS), 
and  it  can’t  handle  double-sided  PC-DOS 
disks.  Note  that  although  PC-DOS  pro¬ 
grams  can  be  transferred  onto  a  CP/M- 
86  diskette,  they  cannot  be  executed  be¬ 
cause  of  differences  in  the  load  image  and 
operating  system  call  conventions. 

dBASE  II  version  2.3B  for  the  IBM 
Personal  Computer,  by  Ashton-Tate. 
Operationally  identical  to  the  CP/M-80 
version,  but  it  requires  96  Kbytes  of 
memory  for  no  obvious  reason.  The  main 
DBASE.COM  file,  the  overlays,  and  the 
message  file  take  up  about  64  Kbytes  of 
disk  space,  leaving  plenty  of  room  on  a 
double-sided  disk  for  other  command 
and  data  files.  The  editing  control  codes 
are  essentially  the  same  as  in  the  8080/ 
Z-80  version;  the  PC’s  arrow  keys  are  also 
active  but  no  use  was  made  of  the  other 
special  function  keys.  In  spite  of  its  rela¬ 
tively  high  price,  this  is  one  of  the  few 
packages  I  have  purchased  that  is  really 
worth  every  penny.  You  will  never  cease 
to  find  new  uses  for  this  powerful  general- 
purpose  data  base  manager. 

Screen  Print  Program  for  the  IBM 
PC,  by  M.  A.  P.  Systems,  Inc.,  1120 
NASDA  Road  One,  Suite  444,  Houston, 
TX  77058.  $44.95.  A  set  of  utility  pro¬ 
grams  which  transfer  a  text  or  graphic 
image  from  the  video  display  to  an  Ep¬ 
son  printer  equipped  with  the  Graftrax 
option.  Distribution  disk  includes  low- 
and  high-speed  versions  of  three  differ¬ 
ent  dump  formats:  normal-size/upright, 
normal-size/rotated,  and  double-size/ 
upright.  After  one  of  the  dump  programs 
is  invoked,  it  becomes  resident  in  RAM 
and  transparent  to  the  operation  of  other 
application  software.  A  screen  dump  can 
be  triggered  at  any  time  by  keying  “Shift- 
Prtsc.”  This  is  a  very  smart  program:  it 
handles  true  bit-mapped  graphics  or  the 
text  mode  “business  graphics”  equally 
well,  and  also  provides  shading  when  re¬ 
producing  a  color  graphics  image.  It  will 
probably  be  most  useful  to  people  who 
wish  to  put  screen  examples  in  their  soft¬ 
ware  manuals.  Very  nicely  implemented. 


Concurrent  CP/M-86  for  the  IBM 
PC,  by  Digital  Research,  Inc.  A  real-time, 
multi-tasking  operating  system  that 
leaves  PC-DOS  light-years  behind.  I  plan 
to  present  a  detailed  review  of  this 
ground-breaking  product  in  the  next 
issue  of  DDJ  (unless  Dave  Cortesi  beats 
me  to  it).  For  now,  it  suffices  to  say  that 
Concurrent  CP/M-86  will  make  possible 
applications  of  unprecedented  power 
in  a  desk-top  computer.  However,  it  is 
not  for  the  user  who  is  faint-of-heart  or 
on  a  limited  budget  —  aside  from  the 
$350  cost  of  the  software,  the  PC  must 
contain  192  Kbytes  of  RAM  to  even  boot 
up  the  operating  system,  and  Digital  Re¬ 
search  recommends  a  minimum  of 
256  Kbytes. 

FASTPAK  8087  support  subroutine 
libraries  for  the  IBM  Personal  Computer, 
from  Microware,  P.  O.  Box  79,  Kingston, 
MA  02364.  $375.00.  Includes  an  8087 
numeric  co-processor  chip  and  your 
choice  of  run-time  libraries  for  the  IBM 
Pascal,  BASIC,  or  FORTRAN  compilers. 
A  package  of  subroutines  and  macros  for 
the  assembly  language  programmer  is  also 
available. 

Coping  with  PC-DOS 

Isaac  Davidian  writes:  “The  com¬ 
ments  in  the  November  1982  column 
about  wiping  out  a  diskette  directory  un¬ 
der  PC-DOS  if  the  incorrect  disk  is  in¬ 
stalled  struck  home  with  me.  I  had  this 
problem  when  making  copies  on  a  single 
drive  by  swapping  disks,  and  accidentally 
inserted  the  wrong  disk. 

“Unfortunately,  I  had  no  backup  and 
the  disk  contained  months  of  work  on 
BASIC  programs.  I  did,  however,  find  a 
way  to  recover  the  files,  and  if  anyone 
has  this  problem  I  would  suggest  setting 
the  disk  aside  in  the  event  they  wish  to 
try  recovery. 

“Briefly  what  I  did  was  to  create  a 
BASIC  program  file  (with  line  numbers  in 
the  60000  range)  on  a  new  diskette.  This 
file  should  occupy  one  of  the  larger  con¬ 
tinuous  blocks  on  the  diskette  and  it 
may  require  saving  the  file  more  than 
once  under  different  names. 

“The  way  to  check  this  is  to  use 
DEBUG  to  read  the  diskette.  Make  note 
of  the  file  location  on  the  diskette  and 
note  the  header  data,  including  file 
names. 

“You  must  then  find,  on  your  dam¬ 
aged  diskette,  each  block  which  contains 
a  portion  of  your  program.  You  then  read 
the  block  from  the  damaged  diskette  and 


write  it  to  the  new  diskette  specifying  the 
sectors  in  the  dummy  file  you  created. 
Before  you  write  to  the  new  diskette, 
however,  you  should  change  the  header 
information  to  conform  to  the  dummy 
file. 

“After  this,  you  can  exit  DEBUG, 
use  BASIC  to  load  the  dummy  file,  and 
then  save  it  under  a  different  name.  The 
process  must  be  repeated  for  each  group 
of  sectors  on  the  damaged  diskette  which 
contains  the  file  you  are  recovering, 

“Since  program  lines  do  not  begin 
and  end  in  sequence  with  the  blocks  of 
data  on  the  diskette,  you  may  lose  por¬ 
tions  of  your  program,  or  you  may  have 
to  wipe  out  a  partial  line  at  the  beginning 
of  succeeding  blocks  that  are  written  to 
the  new  file.” 

Readers  who  are  interested  in  helping 
Isaac  refine  this  technique  further  can 
contact  him  at  5150  N.  Sixth,  Suite  150, 
Fresno,  CA  93710. 

Light  Pens  on  IBM  PC 

The  color /graphics  video  board  on 
the  IBM  Personal  Computer  includes  a 
light  pen  interface,  and  some  light  pen 
control  words  are  included  in  the  PC’s 
BASIC  interpreter.  After  years  of  jeal¬ 
ousy  seeing  light-pen-oriented,  menu- 
driven  applications  on  IBM  mainframe 
systems,  I  bought  the  first  available  light 
pen,  plugged  it  in,  and  prepared  to  have  a 
good  time.  I  am  sad  to  report  that,  al¬ 
though  the  light  pen  interface  will  be 
adequate  for  picking  choices  from  menus, 
some  corners  were  cut  that  will  make  it 
unusable  for  detailed  design  work.  The 
resolution  of  the  controller  on  the  X 
axis  is  limited  to  that  of  text  mode,  even 
when  the  video  board  is  operating  in 
graphics  mode.  For  example,  in  high- 
resolution  graphics  mode,  pointing  the 
light  pen  at  all  of  the  points  (x,y)=(0,0) 
through  (7,0)  will  return  the  value  (0,0), 
the  points  (8,0)  through  (15,0)  all  return 
(8,0),  and  so  forth.  Similarly,  on  the  Y 
axis  the  driver  only  returns  values  that  are 
multiples  of  two. 

Light  pens  for  the  PC  are  manufac¬ 
tured  by  Symtec  Inc.,  15933  W.  8  Mile 
Road,  Detroit,  MI  48235,  and  FTG  Data 
Systems  Inc.,  P.  O.  Box  615-C,  Stanton, 
CA  90680. 

Trigonometric  Algorithms 

Many  new  microcomputer  program¬ 
mers  regard  the  math  function  libraries 
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of  the  commonly  available  interpreters 
and  compilers  as  “magical,”  feeling  that 
their  internal  operation  must  be  too 
complicated  to  understand.  Not  so! 
The  people  who  implemented  most  of 
these  packages  were  not  smarter  than  you 
-  they  just  have  access  to  the  right  infor¬ 
mation.  There  is  an  extensive  body  of 
literature,  worked  out  and  refined  by 
mathematicians  over  a  period  of  many 
years,  that  concerns  itself  with  the  effi¬ 
cient  calculation  of  advanced  numeric 
functions. 

Many  of  the  functions  of  interest  to 
us,  such  as  exponentiation,  sine,  and  co¬ 
sine,  can  be  expressed  as  the  sum  of  an 
infinite  series: 

m 

f(x)  =  an x" 

n=0 

The  appropriate  coefficients  for  each 
function  are  available  in  many  books  of 
mathematical  tables.  Although  these 
series  are  very  exact,  they  tend  to  con¬ 
verge  slowly  and  therefore  require  a  great 
deal  of  computation  time  when  imple¬ 
mented  in  a  program.  There  are  ways 
of  “economizing”  these  series  so  that 
they  converge  more  quickly  and  pro¬ 
duce  results  within  a  predictable  range  of 
error;  two  of  these  methods  are  called 
Chebyshev  approximations  and  rational 
polynomial  approximations. 

For  example,  the  full  series  expan¬ 
sion  of  ex  is: 

Y2  Y3 

ex  =  1  +  x  +  + 

2  6 

_X^_  +  + 

24  120  720 


By  techniques  of  Chebyshev  approxi¬ 
mation,  the  first  seven  terms  of  the  series 
as  shown  above  can  be  reduced  to: 

ex  a  0.9946  +  0.9971  x  + 

0.5430x2  +  0.1776x3 

which  has  about  the  same  percentage 
error  over  the  interval  0  <  x  <  1  and  re¬ 
quires  considerably  fewer  multiplication 
operations.  Such  approximations  are  at 
the  heart  of  all  compiler  run-time  math 
libraries  and  are  also  used  in  pocket  cal¬ 
culators  and  the  microcode  of  numeric 
processors  such  as  the  Intel  8087  or  AMD 
9511. 


For  the  sake  of  giving  you  an  inkling 

how  floating-point  packages  work,  I  will  cos(x)  =  V  1  -  sin2  (x) 

now  present  a  very  simplified  technique 
to  calculate  sine,  cosine,  and  tangent  of  a 

given  angle  directly.  by  virtue  of  the  tri8  identity: 

A  Maclaurin  series  expansion  of  .  2 ,  ■.  i  ,  . 

sin(x)  is:  sm  +  cos  <*>  =  1 


sin(x)  =  x 


where  x  is  in  radians  (2*PI  radians  =  360 
degrees).  This  can  be  economized  by  a 
rational  polynomial  approximation  to: 


This  formula  is  accurate  to  about  1 
part  in  10,000  over  the  interval  0  <  x  < 
7t/4,  a  degree  of  precision  which  is  ade¬ 
quate  for  typical  microcomputer  appli¬ 
cations.  For  x  greater  than  7t/2,  the  error 
increases  substantially  and  the  function 
becomes  essentially  unusable  for  our 
purposes. 

So  now  we  have  a  function  that  will 
give  us  sin(x),  but  only  for  the  first  eighth 
of  a  circle  (a  portion  commonly  called  an 
octant).  How  do  we  generalize  this  so 
that  it  can  be  used  for  any  angle?  Lucki¬ 
ly,  the  trigonometric  functions  have  a 
recurring,  predictable  nature  and  there 
is  a  set  of  “identities”  that  relates  the 
values  of  sine  and  cosine  in  all  of  the  oc¬ 
tants  to  their  values  in  the  first  octant 


We  are  now  in  a  position  to  calcu¬ 
late  the  sine  or  cosine  of  any  angle  direct¬ 
ly,  and  can  also  obtain  tangent(x)  by  the 
relation: 


tan(x)  = 


sin(x) 

cos(x) 


In  summary,  we  can  derive  the  values 
of  sine  or  cosine  for  any  angle  simply  by 
determining  its  octant,  looking  up  the  re¬ 
lationship  for  the  relative  angle  within 
that  octant  to  sin(x)  in  a  simple  table, 
then  applying  the  approximation  func¬ 
tion.  Tangent  is  obtained  by  calculating 
both  sine  and  cosine  and  then  finding 
their  quotient. 

If  you  were  involved  in  a  project  re¬ 
quiring  high-powered  math,  and  did  not 
want  to  waste  months  “reinventing  the 
wheel,”  you  could  buy  the  source  code 
from  United  States  Software  Corpora¬ 
tion,  5470  NW  Innisbrook  Place,  Port¬ 
land,  OR  97229. 


(see  Table  1).  Wherever  cosine  appears  in 
the  table,  you  can  substitute: 


Let  R  = 

Let  S  = 

absolute  value  of  angle  MOD  PI/4 

-1  or  1,  depending  on  the  sign  of  the  angle 

octant 

sine 

cosine 

0 

S  *  sin(R) 

cos(R) 

1 

S  *  cos  (PI/4  -  R) 

sin  (PI/ 4  -  R) 

2 

S  *  cos(R) 

- 1  *  sin(R) 

3 

S  *  sin  (PI /4  -  R) 

-1  *  cos(PI/4  -  R) 

4 

-S  *  sin(R) 

-1  *  cos(R) 

5 

-S  *  cos(PI/4  -  R) 

-1  *  sin  (PI/4  -  R) 

6 

-S  *  cos(R) 

sin(R) 

7 

-S  *  sin(PI/4  -  R) 

Table  1. 

cos(PI/4  -  R) 

The  relationship  of  sine  and  cosine  of  an  angle  in  each  octant.  (Octants  are 
numbered  counter-clockwise  starting  at  0  radians.) 

10 
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Letters  (Continued  from  page  6) 


ing  applications,  as  well.  In  the  state¬ 
ment:  c:=a  *  b;  if  any  of  the  variables  is 
“real”  and  b  =  0,  then  c  will  always  equal 
a.  One  interesting  result  of  this  bug  is  that 
the  system  LOG  procedure  insists  that 
LOG(l  0)  =  2. 

JRT  Pascal  is  the  cheapest  way  to 
find  out  for  yourself  that  Pascal  is  a  mis¬ 
erable  language  for  serious  applications, 
because  too  much  in  the  way  of  input/ 
output  control  has  been  left  out  and  too 
many  redundant  requirements  for  source 
code  were  put  in.  Pascal  was  designed  for 
the  convenience  of  the  compiler  writer, 
rather  than  that  of  the  programmer.  To 
cap  it  off,  any  Pascal  includes  what  is 
probably  the  worst  programming  practice 
known  to  modern  science:  running  once 
through  a  loop  before  making  any  tests 
[REPEAT.  .  .  UNTIL], 

One  wonders  why  anyone  but  a 


“computer  science”  major  would  go 
through  the  effort? 

Yours  very  truly, 

Murray  L.  Lesser 

2474  Hunter  Brook  Road 

Yorktown  Heights,  NY  10598 

Late  for  the  Train 

The  following  letter  was  sent  to  us  as  a 
copy  of  one  sent  to  JRT  Systems,  Inc. 
Gentlemen: 

On  September  5  I  ordered  your  Pas¬ 
cal  program  for  my  North  Star  computer. 
I  inquired  about  my  order  on  September 
25  since  I  did  not  receive  any  shipping 
notice  or  order  acknowledgement. 

On  October  12,  I  had  still  heard  no¬ 
thing  about  my  order,  so  I  telephoned. 
The  woman  at  your  office  assured  me 
that  my  order  would  be  shipped  by  Oc¬ 
tober  15. 

My  latest  VISA  statement  showed 


that  I  was  billed  $29.95  by  your  firm 
on  September  30.  My  order  was  obvious¬ 
ly  not  shipped  then,  nor  have  I  yet  re¬ 
ceived  it. 

I  have  ordered  several  software  pack¬ 
ages  by  mail  in  the  past  and  never  had 
this  poor  service.  Since  I  responded  to 
your  ad  in  Dr.  Dobb’s  Journal,  I  am  let¬ 
ting  them  know  my  experience  with  your 
company. 

If  I  do  not  receive  your  program  or  a 
full  refund  by  November  16,  I  am  regis¬ 
tering  a  complaint  with  the  U.S.  Postal 
authorities. 

Yours  sincerely, 

J.  H.  Peters 
929  Robin  Drive 
Seaford,  Delaware  19973 

You  ain’t  seen  nothin’  yet!  See  this 
month’s  Software  Review  for  still  more 
on  JRT  Pascal  from  two  who  have  re¬ 
ceived  their  copies.  -Ed.  j 
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AUGUSTA 

An  ADA  Subset  for  Micros 


Editor’s  note:  Since  the  Department  of 
Defense,  DoD,  often  referred  to  as  the 
Directors  of  Death,  has  not  seen  fit  to 
franchise  any  “official”  subset  of  Ada, 
we  will  all  be  seeing  creative  adaptations 
of  it  as  time  goes  on. 

Augusta  is  the  first  of  these  ADAoids 
to  run  on  a  portable  micro,  as  it  was 
tested  effectively  on  the  Osborne.  It  also 
runs  on  any  Z80 -based  system  and  will 
soon  be  available  in  MS-DOS.  Augusta 
is  a  copyrighted  product  soon  to  be 
released  as  a  package  to  retail  for  under 
$100.00,  tax  and  license  included.  This 
article  is  in  fact  the  first  serial  of  four  in¬ 
stallments  to  be  run  every  other  month 
in  Dr.  Dobb’s.  The  four  segments  com¬ 
prise  a  book  which  should  be  available 
in  1 984.  The  lag  period  between  serializa¬ 
tions  is  designed  to  allow  feedback 
which  both  DDJ  and  the  author  encour¬ 
age.  Ed  Mitchell  is  twenty -four  years 
old. 

The  Augusta1  compiler  introduced  in 
this  four-part  series  implements  a 
subset  of  the  U.  S.  Department  of 
Defense  Ada2  programming  language. 
The  series  describes  the  Augusta  language, 
the  “p-code”  interpreter,  the  recursive 
descent  parser  and  the  Augusta  com¬ 
piler. 

Ada  is  a  strongly  typed  and  struc¬ 
tured  language  with  influences  from  Pas¬ 
cal,  Algol  and  SIMULA.  (See  reference 
1.)  “Ada”  is  a  registered  trademark  of  the 
U.S.  DoD  and  only  compilers  that  con¬ 
form  to  the  formal  Ada  definition  may 
use  the  name  “Ada.”  For  that  reason, 
this  subset  implementation  is  named 
“Augusta.”  Augusta  is  not  a  pure  subset 
implementation  of  Ada  and  does  not  pur¬ 
port  to  be  an  Ada  Compiler  either  now  or 
in  the  future. 

Augusta,  like  Ada,  was  named  for 
Augusta  Ada  Byron,  the  Countess  of 
Lovelace  and  one  of  the  first  program¬ 
mers,  having  worked  with  Charles 
Babbage’s  mechanical  computing  engines 
during  the  mid-19th  century. 

Augusta  is  written  in  Microsoft 
BASIC-80,  originally  on  an  Osborne  1 


by  Edward  Mitchell 


Copyright  ©  1983  by  Edward  Mitchell, 
Graduate,  Computer  and  Information 
Sciences,  University  of  California,  Irvine. 


computer.  The  compiler  will  run  on  other 
microcomputers  with  little  or  no  trans¬ 
lation,  including  the  IBM  Personal  Com¬ 
puter,  the  Apple  II  with  Z80  Softcard, 
and  the  Radio  Shack  Model  II.  The  com¬ 
piler  generates  code  for  a  hypothetical 
“stack”  machine.  This  stack  machine  exe¬ 
cutes  “pseudo-code”  or  “p-code”  in¬ 
structions  and  is  simulated  by  a  p-code 
interpreter  program. 

When  Augusta  is  run  as  an  inter¬ 
pretive  BASIC  program,  it  compiles  at 
about  40  to  50  lines  per  minute.  Once 
Augusta  is  compiled  with  the  Microsoft 
BASCOM  compiler,  it  compiles  Augusta 
source  code  at  well  over  300  lines  per 
minute.  The  BASIC  version  of  the  p-code 
interpreter  (described  in  Part  2)  was  used 
during  system  development  as  a  test  bed. 
A  CP/M  Z80  version  of  the  interpreter 
executes  p-code  programs  10%  to  80% 
faster  than  CBASIC  programs,  depending 
on  the  benchmark  test. 

When  run  using  interpretive  BASIC, 
the  compiler  requires  about  17K  bytes  of 
memory  after  BASIC-80  has  been  loaded, 
plus  about  4K  for  storage  of  Augusta’s  in¬ 
ternal  variables.  On  the  Osborne  1 ,  that 
leaves  about  8K  bytes,  which  is  used  al¬ 
most  exclusively  for  symbol  table  space 
at  17  bytes  per  symbol. 

The  compiled  code  is  written  to  a 
disk  file  and  is  loaded  into  virtual  mem¬ 
ory  at  run  time  by  the  p-machine  simu¬ 
lator.  Since  the  p-machine  is  designed 
specifically  to  execute  Augusta  programs, 
the  compiled  version  of  a  program  is  ex¬ 
tremely  compact. 

Part  1  of  this  four- part  series  de¬ 
scribes  the  Ada  subset  that  forms  the  Au¬ 
gusta  language  and  provides  examples  of 
Augusta  programs.  Part  2  is  a  detailed 
description  of  stack  machines  and  the  Au¬ 
gusta  p-machine  in  particular.  Part  3  is 
a  general  introduction  to  recursive  de¬ 
scent  compilers.  Part  3  also  presents  the 
first  half  of  the  compiler  source  listing 
with  the  second  half  appearing  in  Part  4. 
Part  4  concludes  the  series  by  describ¬ 
ing  the  compiler’s  internal  operation. 

Defining  the  Language 

Before  the  compiler  can  be  written, 
we  must  precisely  define  the  syntax  of 
the  Augusta  language.  Obviously,  much 
of  the  full  Ada  definition  must  be  omit¬ 
ted.  For  example,  full  Ada  provides  for 
the  concurrent  execution  of  several  pro¬ 
cesses.  But  multiprocessing  requires  an 
operating  system  to  manage  system  pro¬ 


cesses  and  resources.  Hence,  multiple 
processes  would  be  difficult  to  fit  into  a 
small  implementation. 

Similarly,  “packages”  or  program  li¬ 
braries  entail  substantial  overhead  inside 
the  compiler.  Other  features  must  be  left 
out  because  the  compiler  is  written  in 
BASIC  and  their  implementation  would 
be  difficult. 

Based  on  these  and  other  restrictions, 
a  suitable  Ada  subset  was  chosen.  Ideally, 
the  subset  will  be  sufficient  to  rewrite 
Augusta  in  Augusta.  Further,  programs 
written  in  Augusta  should  be  upwardly 
compatible  to  Ada  with  only  minor  modi¬ 
fications. 

Two  extensions  were  made  to  the 
Ada  subset.  In  procedure  calls,  the 
symbol  is  placed  before  variable  identi¬ 
fiers  when  passing  parameters  by  refer¬ 
ence  instead  of  by  value.  The  use  of  the 
symbol  is  described  in  greater  de¬ 
tail  later  in  this  article.  In  Augusta, 
strings  are  represented  internally  more 
like  UCSD-style  Pascal  strings  than  like 
Ada  strings. 

The  syntax  diagrams  in  Figure  1  are 
a  concise,  graphic  description  of  the  lan¬ 
guage.  The  diagrams  show  the  sequence 
of  language  symbols  or  “syntax”  that 
make  up  a  valid  Augusta  program.  Items 
within  circles  are  language  keywords  like 
PROCEDURE”,  “IF”,  “THEN”,  and  so 
on,  or  “tokens”  such  as  “(”,  or 

“>  =  ”.  Items  within  rectangles  are  the 
names  of  descriptions  shown  elsewhere  in 
Figure  1 . 

Syntax  diagrams  show  the  language 
in  an  outline-Uke  form.  For  example, 
a  “COMPILATION”  is  an  optional 
“PRAGMA”  (a  special  type  of  program 
comment)  followed  by  the  keyword 
“PROCEDURE”  followed  by  a  “PROC. 
HEADER”  followed  by  a  period.  “PROC. 
HEADER,”  defined  below  “COMPILA¬ 
TION,”  describes  the  syntax  for  a  proce¬ 
dure. 


An  Overview  of  the  Language 

Augusta  programs  look  a  lot  like 
Pascal.  But  there  are  important  differ¬ 
ences,  particularly  when  compared  to 
the  “tiny”  versions  of  Pascal.  Listing  1 
shows  a  sample  program  listing  produced 
by  the  Augusta  compiler.  Note  that  pro¬ 
gram  “comments”  are  marked  by  placing 
a  double  hyphen  before  the  com¬ 

ment  text.  The  four  columns  to  the  left 
of  the  source  text  represent  (1)  the  line 
number  in  the  source  text,  (2)  the  proce¬ 


ll 
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dure  number,  (3)  the  number  of  bytes  of 
code  generated  up  to  that  line  for  the  cur¬ 
rent  procedure,  and  (4)  the  offset  from 
the  frame  mark  for  the  variable  defini¬ 
tions. 

Augusta  programs  are  typically  split 
into  several  procedure,  function,  and  vari¬ 
able  definitions.  Variable  and  procedure 
names  consist  of  alphabetic  and  numeric 
characters  and  the  underscore  For 

example,  all  of  the  following  may  be  Au¬ 
gusta  identifiers, 

X 

ALPHA 

STORE19 

NEW_LINE 

COST_  FUNCTION 

Identifiers  may  be  any  length  (up  to  255 
characters),  but  only  the  first  8  charac¬ 
ters  are  significant.  For  example, 

ALPHABETA 

and 


refer  to  the  same  identifier  because  the 
first  8  characters  are  the  same.  (The 
underscore  character  does  not 

count  as  a  significant  part  of  the  identi¬ 
fier  name:  “X_Y”  is  equivalent  to  “XY” 
since  the  is  not  stored  in  the  symbol 
table.) 

Augusta  provides  four  data  types: 
INTEGER,  CHARACTER,  STRING,  and 
BOOLEAN,  plus  constant  definitions. 
(Four  special  types  are  also  provided  and 
are  discussed  later.)  In  addition,  one  di¬ 
mensional  arrays  of  each  type  are  permit¬ 
ted  (see  Listing  1  for  examples  of  varia¬ 
ble  declarations). 

INTEGER  variables  hold  numbers  in 
the  range  -32768  to  32767.  For  example, 

I,  J,  K:  INTEGER; 

defines  the  symbols  “I”,  “J”,  and  “K”  as 
integer  variables.  They  might  be  assigned 
values  as  follows: 


I  :=35 ; 

J:=I*I;  —  J  equals  I  squared 

K:=J+J;  —  K  equals  the  sum  of  I 

squared 

BOOLEAN  variables  hold  a  TRUE  or 
FALSE  value  and  are  often  used  as  “flag” 
variables.  For  example,  a  loop  is  to  be 
repeated  until  a  certain  condition  tests  as 
false.  In  Augusta  this  might  be  written  as, 

MOREINPUT  :=  TRUE; 

WHILE  MOREINPUT 

LOOP 

—  process  input 

END  LOOP; 

The  code  that  processes  the  input  sets 
MOREINPUT  to  FALSE  when  the  loop  is 
completed.  Augusta  treats  any  non-zero 
value  as  TRUE  and  a  zero  value  as 
FALSE. 

CHARACTER  variables  hold  a  single 


Listing  1 . 

45 

2 

338 

8 

CASE  RESPONSE  IS 

/ 

46 

2 

346 

8 

WHEN  1  =>  HIBND  :=  GUESS  -  1; 

47 

2 

352 

8 

WHEN  2  =;  L0WBND  :=  GUESS  ♦  1; 

2 

0 

0 

0  PRAGMA  CRTtON);  -  LIST  COMPILATION  TO  SCREEN 

48 

361 

8 

WHEN  3  =>  RETURN  COUNT; 

3 

0 

0 

49 

366 

8 

4 

0 

0 

0 

--  Augusta  DEMONSTRATION  PROGRAM 

50 

2 

394 

8 

END  CASE; 

5 

0 

0 

0 

--  Written  by  Edward  Mitchell,  07/29/82 

51 

406 

8 

6 

0 

0 

0 

52 

7 

3 

COUNT  :=  COUNT  ♦  1; 

7 

0 

0 

0  PROCEDURE  NUM6UESS  IS 

8 

1 

0 

14 

L0NBND  :  INTEGER;  —  The  lower  bound  of  the  guessing  interval 

54 

2 

412 

8 

END  LOOP; 

9 

1 

0 

2 

HIBND  :  INTEGER;  —  The  upper  bound  of  the  interval 

10 

1 

0 

4 

AGAIN  :  BOOLEAN;  —  Set  to  FALSE  if  the  user  doesn’t  want  tore  gates 

412 

8  END;  --  OF  FUNCTION  GUESSER 

11 

1 

0 

6 

CH  2  CHARACTER;  —  Dutty  variable  for  input 

12 

1 

,0 

8 

S  :  STRING;  --  Outty  string  for  input 

13 

1 

0 

89 

N6UESSES:  INTEGER;  —  1  of  guesses  *ade  by  cotputer 

59 

1 

416 

91 

BEGIN  -  PROCEDURE  6UESSNUN 

1 

0 

91 

15 

1 

0 

91 

FUNCTION  GUESSER  RETURN  INTEGER  IS 

16 

0 

14 

RESPONSE  :  INTEGER;  —  Player's  Hi,  Lo,  or  Equal  response 

61 

1 

4 

91 

PUTLINE' 'NUMBER  GUESSING  GAME');  NEWLINE; 

17 

7 

o 

2 

COUNT  :  INTEGER;  —  Counts  the  #  of  guesses 

62 

1 

30 

91 

PUTLINE ('Choose  a  nutber  between  l  and  1000  and  the'); 

18 

2 

0 

4 

GUESS  :  INTEGER;  ~  the  guess 

63 

1 

76 

91 

PUTLINE ( 'cotputer  will  try  to  guess  your  choice.'); 

19 

2 

0 

6 

LASTGUESS:  INTEGER;  --  the  previous  guess 

64 

1 

119 

91 

20 

7 

0 

8  BEGIN 

65 

1 

119 

91 

WHIlE  AGAIN 

21 

2 

0 

8 

COUNT  2=  1;  --  Initial  sote  stuff 

66 

1 

119 

91 

LOOP 

22 

2 

4 

8 

GUESS  2=  0; 

6/ 

124 

23 

n 

8 

8 

LOOP 

68 

1 

124 

91 

NEWLINE; 

24 

2 

8 

8 

LASTGUESS  2=  6UESS; 

69 

1 

126 

91 

PUTSTR ('Press  RETURN  after  you  have  chosen  your  nutber:  “); 

25 

2 

12 

8 

GUESS  2=  (L0WBND  +  HIBND)  /  2;  --  Uses  a  binary  search 

70 

1 

179 

91 

GETSTR(JS); 

26 

2 

22 

8 

71 

1 

183 

91 

27 

2 

22 

8 

IF  LASTGUESS  =  GUESS  THEN 

l 

183 

91 

L0WBND  ;=  1; 

28 

2 

28 

8 

PUTLINE  ('You  tessed  up  your  entries'  I  guarantee* ); 

73 

1 

187 

91 

HIBND  :=  1000; 

29 

7 

72 

8 

PUTLINE  (*to  guess  your  nutber  in  less  than  11  ■oves"); 

30 

2 

118 

8 

PUTLINE  (‘but  you  entered  a  wrong  response'  and  that*); 

75 

1 

193 

91 

NGUESSES  :=  GUESSER;  —  Call  the  guessing  routine 

31 

2 

164 

8 

PUTLINE  ('really  upsets  «e.  I  never  take  ustakes'); 

76 

1 

198 

91 

NEWLINE; 

32 

2 

208 

8 

PUTLINE  ('like  that  .  .  ."); 

77 

1 

200 

91 

PUTSTR (“Nutber  of  guesses  =  "l; 

33 

2 

227 

8 

RETURN  COUNT; 

78 

1 

224 

91 

PUTINT (NGUESSES);  NEWLINE;  NEWLINE; 

34 

2 

229 

8 

END  IF; 

1 

232 

91 

35 

2 

229 

3 

80 

1 

232 

91 

2 

229 

8 

NEWLINE;  NEWLINE; 

31 

1 

232 

91 

PUTSTRCDo  you  wish  to  plav  again  (CR=ies  N=No '■ 

233 

8 

PUTSTR ( 'Guess  #  '); 

32 

1 

278 

91 

GETCHAR (SCH 1 ; 

38 

2 

245 

8 

PUTINT (COUNT); 

83 

1 

282 

91 

NEWLINE; 

39 

2 

248 

8 

PUTSTR ('  Cotputer' s  Guess  =  ’); 

34 

1 

284 

91 

IF  CH='N'  THEN  AGAIN  :=  FALSE; 

40 

2 

274 

3 

PUTINT (GUESS);  NEWLINE; 

85 

i 

296 

91 

END  IF; 

41 

279 

8 

86 

l 

296 

91 

END  LOOP; 

42 

2 

279 

8 

PUTSTR' 'Enter:  l=Too  High,  2=Too  Low,  3=Equal  or  Quit  7  "); 

87 

i 

91 

END;  -  OF  PROGRAM 

43 

2 

334 

8 

GET  I NT (^RESPONSE) ; 

44 

2 

338 

8 

End  Listing 

16 
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character.  An  example  definition  looks 
like, 

CH  : CHARACTER; 

A  character  constant  is  delineated  by  sin¬ 
gle  quote  marks:  ‘A’  or  ‘B’.  The  variable 
CH  is  assigned  the  value  of  ‘A’  by 
entering 

CH  :=  ‘A’; 

STRINGs  are  similar  to  the  strings 
defined  in  UCSD  Pascal  but  are  not  the 
same  as  arrays  of  CHARACTER.  The 
declaration 

S  :  STRING; 

gives  S  a  length  of  128  characters.  Char¬ 


acter  string  constants  are  enclosed  in 
double  quotes  (note  the  difference 
between  strings  and  characters).  For 
example,  an  assignment  might  be  made  to 
S  by  entering, 

S  :=  “The  moon  will  be  in  total 
eclipse  on: 

However,  unlike  Pascal,  a  string  in  Augus¬ 
ta  is  not  an  array  of  characters.  The  nota¬ 
tion  S(i)  refers  to  the  i th  element  of  an 
array  S,  not  to  character  i  within  a  string. 
Instead,  several  “built-in”  procedures 
and  functions  are  provided  by  Augusta  to 
manipulate  strings.  These  procedures  are 
summarized  in  Table  I. 


Table  I. 

Summary  of  Predefined  Augusta  Procedures  and  Functions. 

PROCEDURE  PUT  I NT  <  I  :  INTEGER  >; 

Outputs  1  to  the  display.  I  may  be  either  a  variable  or  an 
en press! on . 

PROCEDURE  PUT SIR  <  S  s  OUT  STRING  ); 

Outputs  S  to  the?  display.  S  may  be  either  a  string 
variable,  prefaced  by  the  special  "3"  symbol,  or  a  string 

constant . 

PROCEDURE  PUTCHAE  (  C  s  CHARACTER  >; 

Outputs  the  single  character  C. 

PROCEDURE  GET I NT  <  1  :  OUT  INTEGER  ); 

Reads  an  integer  typed  at  the  keyboard,  returning  the 
entered  number  in  I. 

PROCEDURE  GETSTR  (  S  :  OUT  STRING  ) ; 

Reads  a  string  from  the  keyboard,  returning  the 
input  in  S. 

PROCEDURE  GETCHAR  <  C  :  OUT  CHARACTER  ) ; 

Reads  a  single  character  from  the  keyboard,  returning  the 
input  in  S. 

PROCEDURE  NEWL I NE ; 

Prints  a  CR/LF  sequence. 

PROCEDURE  PUTLINE  <  5  s  OUT  STRING  ); 

Equivalent  to  PUTSTPOS)  followed  by  NEWLINE; 

FUNCTION  PEEK  (  I  :  INTEGER  )  RETURN  INTEGER 

Equivalent  to  Microsoft  BASIC-GO’ s  PEEK  function,  this 
function  returns  the  value  of  the  byte  at  memory  address  1. 

PROCEDURE  POKE  (  A,  I  :  INTEGER  ); 

As  above,  POKE  is  similar  to  BASIC— 80’ s  POKE,  and  is  used 
to  write  the  byte  value  I  to  memory  address  A. 

PROCEDURE  SUBSIR  <  SI,  S2  :  OUT  STRING;  START,  LEN  :  INTEGER  >; 

Copies  a  substring  from  S2,  beginning  at  byte  START  and 
continuing  for  length  bytes,  into  SI. 

FUNCTION  CHAR  (SI  :  OUT  STRING;  POSITION  s  INTEGER  >  RETURN  CHARuLILP 
Returns  the  character  at  byte  POSITION  in  SI. 

PROCEDURE  APPEND  <  SI,  82  :  OUT  SIRING  ); 

Appends  string  S2  on  to  the  end  of  Si. 

PROCEDURE  ASSIGN  (SI  :  OUT  STRING;  POSITION,  VALUE  s  IN  I  EGER  ' ; 
Changes  the  byte  at  POSH  ION  in  Si  to  VALUE. 
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The  length  of  a  string  is  obtained  by 
a  reference  to  the  variable’s  LENGTH 
attribute,  as  shown  below, 

I  :=  S’LENGTH; 

returns  the  current  length  of  string  S. 
Augusta  also  supports  an  attribute  for 
array  variables, 

X’LAST 

which  returns  the  dimensioned  size  of 
array  X. 

Constant  identifiers  are  declared 
Eke  variables  as, 

TEN  :  CONSTANT  :=  10; 

—  symbol  “TEN”  has  a  value  10 

A  constant  identifier  can  be  used  any¬ 
where  that  an  expUcitly  written  constant 
is  used.  For  example, 

1  :=  TEN  +  TEN; 

would  assign  the  value  20  to  I.  Note  that 
Augusta  does  not  provide  constant 
strings;  only  integers,  characters,  and 
booleans  are  permitted  as  constant  iden¬ 
tifiers. 

Constants  may  be  entered  in  any 
base,  2  through  16,  by  using  Ada’s  base 
conversion  notation.  For  example, 

2  #  1 0 1 0 1 1 

is  a  constant  in  base  2. 

1 6#FF 

is  a  hexadecimal  constant. 

Augusta,  like  Ada,  requires  most 
variables  to  be  defined  before  they  can 
be  used  in  a  program.  But  here  are  some 
exceptions.  In  particular,  a  FOR  loop 
control  variable,  such  as  I,  in 

FOR  I  IN  1..10 

is  automatically  defined  as  an  integer  that 
is  local  to  the  scope  of  the  FOR  loop. 
Once  the  FOR  loop  is  completed,  the 
definition  of  I  goes  away.  At  first  glance 
this  may  seem  pecuEar,  but  it  answers 
the  classic  question:  “What  is  the  value 
of  I  at  the  end  of  the  loop?”  Is  it  10  or 
11?  By  removing  the  definition  of  the 
loop  control  variable  at  loop  exit,  there 
can  be  no  ambiguity;  1  is  truly  undefined. 

Variables  may  also  be  declared  local 
to  a  BEGIN-END  block  by  using  the 
DECLARE  statement  as  showp  in  Listing 
2.  Once  the  program  exits  the  block,  both 
the  definition  of  the  variables  and  the 
storage  space  that  they  occupy  are  made 
free. 

In  the  declarations  area  of  a  proce¬ 
dure  or  in  the  declarations  following  a 
DECLARE  statement,  the  different 
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types,  including  constants,  may  appear  in 
any  order.  However,  no  more  than  15 
identifiers  may  appear  in  a  list  of  identi¬ 
fiers  as  in, 

I,J,K,L,M  :  INTEGER; 

The  total  number  of  identifiers  allowed  in 
a  program  is  dependent  on  the  amount  of 
memory  your  computer  has.  Each  symbol 
table  entry  requires  17  bytes.  On  the 
Osborne  1 ,  over  400  identifiers  may  be 
declared  and  simultaneously  in  use.  Iden¬ 
tifiers  that  are  “local”  to  a  procedure  or 
function  are  removed  from  the  symbol 
table  after  the  procedure  or  function 
has  been  compiled.  This  means  that  the 
total  number  of  identifiers  used  in  a 
program  may  be  far  in  excess  of  400, 
provided  that  most  are  defined  locally 
to  procedures  and  functions. 


Arrays 

Arrays  are  always  one  dimensional 
and  begin  at  0.  Example, 

X  :  ARRAY  (10)  OF  STRING; 

defines  11  string  elements  X(0),  X(l), 
.  .  .,  X(10),  each  up  to  80  characters 


long.  Augusta  also  supports  arrays  of 
integers,  characters  and  booleans. 

Type  Conversions 

Augusta,  like  full  Ada,  permits 
variables  and  expressions  to  be  convert¬ 
ed  to  other  types.  For  example,  if  you 
need  to  obtain  the  ASCII  value  of  a  char¬ 
acter  variable  CH,  you  type, 

I  :=  INTEGER  (CH); 

The  “type”  identifier  INTEGER  is  used 
like  a  function  call.  The  single  parameter 
CH  is  converted  to  an  integer.  Similarly, 
to  convert  an  integer  65  into  the  corre¬ 
sponding  ASCII  character  ‘A’,  you  would 
type, 

CH  :=  CHARACTER  (65); 

Statements  in  Augusta 

The  basic  assignment  statement  has 
already  been  shown: 

I  :=  35+78; 

Augusta  supports  the  usual  arithmetic 
operators,  including  addition,  subtrac¬ 


tion,  unary  minus,  multiplication,  divi¬ 
sion  and  modulus.  The  complete  set  of 
operators  is  shown  in  Table  II. 

The  operations  follow  the  usual 
arithmetic  heirarchy  as  shown  below: 

(1)  *,/,  and  MOD  are  applied  first. 

(2)  +  and  -  are  applied  second. 

(3)  Relational  operators,  such  as  “=” 
and  “<=”,  appear  third. 

(4)  Boolean  operations  AND  and  OR 
are  last. 

For  example,  the  expression  3  +  5  *  8  is 
evaluated  as  3  +  (5  *  8)  because  multipli¬ 
cation  comes  before  addition. 


Conditional  Statements 

IF-THEN-ELSE  and  IF-THEN- 
ELSEIF  logic  provide  for  conditional  exe¬ 
cution  of  program  statements.  As  shown 
by  Table  III,  multiple  statements  may 
follow  THEN  or  ELSE  without  the  use  of 
a  BEGIN-END  block.  An  END  IF  or  ad¬ 
ditional  ELSE  or  ELSEIF  clause  termi¬ 
nates  the  sequence  of  statements. 

Augusta  provides  an  unusual  “short 
circuit”  conditional.  In  most  program- 


Table  II. 

Summary  of  Augusta  arithmetic  operations. 

+  Addition,  as  in  3  +  5  gives  63 

-  Subtraction,  as  in  1.00  -  25  gives  75 

and  unary  minus,  as  in  -9. 

*  Multiplication,  as  in  10  *  5  gives  50 

/  Division,  as  in  50  /  5  gives  10 

MOD  Modulus,  as  in  7  MOD  3  gives  a  remainder  at 
(the  remainder  ot  X/Y) 

NOT  Unary  boolean  "NOT". 

AND /AND  1  HEN 

Boolean  AND 

OR /OR  ELSE 

Boolean  OR 

-  equality  comparisons 

/=  not  equal 

less  than 

<  =  .less  than  or  equal 

>  greater  than 

>-  greater  than  or  equal 


Table  III. 

Shown  here  are  several  examples  of  Ada’s  IF-THEN- 
ELSE/ELSEIF-END  IF  conditional  statements.  If  IF, 
except  for  ELSEIFs,  must  have  a  matching  END  IF. 


( a ) 

IF  A=.B  THEN  FOUND  *«  i  RUE; 
END  IF; 

<b> 

IF  A=B  THEN  FOUND  :  =  TRUE; 
ELSE  FOUND  5=  FALSE; 

FIJI)  IF; 


IF  A~B  THEN  FOUND  :=  TRUE; 
ELSEIF  A=B+ 1  THEN  EXIT  SEARCH; 
ELSEIF  A— O  THEN  Is =1+1; 

ELSE  F'UTL  I NE  <  "  M 1 SMA  1"CH  "  )  ; 

END  IF; 

(d ) 

TE  A=B  THEN  FOUND  s=  TRUE; 

ELSE 

IF  A=B+1  THEN  EXIT  SEARCH; 
ELSE 

IF  A=0  THEN  1  :=  I  +  1; 

END  IF; 

END  IF; 

END  IF; 
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ming  languages,  the  statement, 

IF  (NOO)  AND  (J/N  =  l)  THEN. . . 

causes  both  conditions  to  be  tested  re¬ 
gardless  of  the  outcome  of  the  first  com¬ 
parison.  Of  course,  if  N  =  0  the  program 
will  likely  halt  with  a  divide-by-zero  er¬ 
ror.  The  programmer  probably  meant 
to  write: 

IF  (N<>0)  THEN 
IF  (J/N=l)  THEN  .  .  . 

In  this  form  the  second  condition  will 
only  be  evaluated  when  N  is  not  equal 
to  0. 


Short-circuit  notation  provides  a 
shorthand  method  of  writing  this  type  of 
conditional.  An  example  is  given  below 
(Note:  In  Ada  “/=”  is  the  “not  equal” 
relational  operator): 

IF  (N/=0)  AND  THEN  (J/N  =  l) 
THEN . . . 


COMPILATION 


PRAGMA  INFO 


' - ^PROCEDURE^- 


PROC  HEADER 


o 


PROC  HEADER 


If  N  is  equal  to  0  then  the  second  condi¬ 
tion  is  never  evaluated. 

Similarly,  if  any  one  of  several  con¬ 
ditions  is  true,  then  it  may  not  be  neces¬ 
sary  to  evaluate  all  the  conditions.  For 
example, 

IF  (A  =  l )  OR  (B  =  2)  OR  (C  =  3) 
THEN... 


PROC  FORMAL  PART 


0-1 

f 

PROC  PARAM 
DECL 

r° 

>— © — 

might  be  written  in  Ada  as 

IF  (A=l)  OR  ELSE  (B=2)  OR  ELSE 
(C=3)  THEN  . . . 

If  A  is  equal  to  1 ,  none  of  the  other  con¬ 
ditions  will  be  tested  and  control  will 
immediately  transfer  to  the  THEN  part 
of  the  statement. 

The  short-circuit  conditional  behaves 
exactly  like  a  boolean  expression.  The 
statement 

B  :=  (A  =  l )  OR  ELSE  (B=2); 


PROC  PARAM  DECL 


functions  similarly  to  a  boolean  OR  of 
(A=l)  OR  (B  =  2). 


Looping  Statements 

The  LOOP-END  LOOP  construction 
forms  the  basic  looping  mechanism.  The 
statement 

LOOP 

—  process  statements 
END  LOOP; 


FUNC  HEADER 


is  an  infinite  loop.  By  placing  a  modifier 
before  the  loop,  the  number  of  itera- 


(Figure  1  continued  on  next  page) 
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tions  is  restricted.  Example: 

FOR  I  IN  1.  .10 
LOOP 

—  process  statements 
END  LOOP; 

is  a  traditional  FOR  loop,  executing  the 
enclosed  statements  ten  times.  A  FOR 
loop  can  also  decrement  the  control  vari¬ 
able  by  specifying  the  REVERSE  option, 
as  in, 

FOR  I  IN  REVERSE  10.  .1 

Note  that  I  is  automatically  defined  as  an 
integer  variable  that  is  local  to  the  loop. 

A  WHILE  modifier  executes  the  en¬ 
closed  loop  as  long  as  the  control  expres¬ 
sion  remains  true.  A  simple  WHILE  loop 
might  look  like 

I  :=  1; 

WHILE  I  <  1 0 
LOOP 

I  :=I+  1; 

END  LOOP; 

The  loop  is  repeated  for  values  of  I  from 
1  to  9.  On  exit,  I  equals  10.  The  looping 
condition  is  always  tested  before  the 
loop  is  executed.  A  Pascal-like  REPEAT- 
UNTIL  loop,  where  the  condition  is 
tested  at  the  end  of  the  loop,  is  possible 
and  is  shown  in  the  description  of  the 
EXIT  statement. 


The  CASE  Statement 

The  CASE  statement  uses  the  value 
of  an  expression  to  select  one  of  several 
conditions.  For  the  most  part,  it  is  simi¬ 
lar  to  the  CASE  statement  in  Pascal. 
Example: 

CASECH  IS 

WHEN  ’A’  !  ’B’  => 

DOCOMMAND; 

PUTLINE(“COMMAND 
A  OR  B  COMPLETED”); 

WHEN  ’C’  =>  DOCOMMANDC; 

WHEN  OTHERS  => 

DOOTHERS; 

END  CASE; 

In  the  example  above,  if  CH  has  either 
the  value  ‘A’  or  ‘B’  (“!”  separates  items 
in  a  CASE  selector  list),  then  the  proce¬ 
dure  DOCOMMAND  is  executed.  If  CH 
is  neither  ‘A’,  ‘B’  nor  ‘C’,  then  the 
OTHERS  part  of  the  CASE  statement  is 
executed.  The  OTHERS  condition  is  op¬ 
tional  and  may  be  omitted.  If  OTHERS  is 
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FORI  IN  1..10 

LOOP 

PUT_INT(I);  NEW_  LINE; 

EXIT; 

END  LOOP; 

which  prints  1  and  immediately  termi¬ 
nates  the  loop. 

The  EXIT  directive  may  be  used  in 
combination  with  a  LOOP- END  LOOP 
block  of  statements  to  perform  a  Pascal¬ 
like  REPEAT-UNTIL.  In  the  REPEAT 
statement,  the  loop  is  always  executed  at 
least  once  since  the  condition  test  is  per¬ 
formed  at  the  end  of  the  loop.  In  Augus¬ 
ta,  a  REPEAT-UNTIL  type  statement  is 
coded  as 

I  :=  10; 

LOOP 

PUT_INT(I );  NEW_  LINE; 

I  :=  1+  1; 

EXIT  WHEN  I>  5 ; 

END  LOOP; 

The  above  will  always  print  the  initial 
value  of  I. 

Pragma  Compiler  Control 
Comments 

“Pragmas”  are  a  special  type  of  com¬ 
ment  statement  that  acts  as  an  instruction 
to  the  compiler.  Augusta  uses  pragmas  to 
“include”  additional  source  texts  during 
the  current  compilation  and  to  control 
the  printing  of  the  compiler  generated 
source  listing. 

During  compilation,  Augusta  can 
temporarily  stop  reading  the  primary 
source  file  and  begin  reading  another 
source  file.  When  the  end  of  the  second 
source  file  is  reached,  the  compiler  re¬ 
sumes  reading  the  original  file  at  the 
point  where  it  was  suspended.  An  “in¬ 
clude”  pragma  has  the  form 

PRAGMA  INCLUDE  (“Filename”); 

Included  files  may,  in  turn,  include  other 
files.  The  nesting  level  is  determined  by 
the  maximum  number  of  files  that 
BASIC  allows  open  at  one  time. 

Procedures  and  Parameter 
Passing  (Table  IV) 

The  basic  program  unit  is  a  PROCE¬ 
DURE  or  FUNCTION  that  optionally 
contains  its  own  set  of  “local”  variables. 
Memory  space  for  local  variables  is  al¬ 
located  when  the  procedure  is  called 


and  is  made  free  when  the  procedure 
returns  to  its  caller. 

Parameters  may  be  passed  as  either 
“IN”  or  “OUT”  type.  IN  parameters  are 
passed  by  value.  That  means  that  the 
called  procedure  is  given  a  copy  of  the 
data  to  process.  An  assignment  to  an 
IN  parameter  variable  has  no  effect  out¬ 
side  the  procedure.  Conversely,  if  an  OUT 
parameter  is  assigned  a  new  value,  it  is 
passed  outwards  to  the  calling  procedure. 

An  symbol  before  an  identifier 
in  the  parameter  list  tells  the  compiler 
to  pass  the  parameter  by  reference  rather 
than  by  value.  The  symbol  must  be 
used  when  the  parameter  is  defined  as 


OUT.  For  reasons  that  will  be  explained 
in  Part  4  (scheduled  for  the  June,  1983 
issue  of  DDJ),  the  compiler  does  not 
perform  any  type  checking  of  parameters 
at  the  point  of  the  procedure  call.  In  ad¬ 
dition,  string  variables  and  arrays  must  al¬ 
ways  be  passed  by  reference  -  never  by 
value.  The  following  statement  illustrates 
the  passing  of  a  variable  reference  to  a 
procedure  by  preceding  it  with  the 
symbol: 

SEARCHROUTINE  (  ELEMENT, 
©FOUND  ); 

where  FOUND  is  a  boolean  variable  set  to 
TRUE  or  FALSE  by  the  search  routine. 


Table  IV. 

Parameters  to  procedures  may  be  passed  either  “by  value”  or  “by  reference.” 
When  passed  “by  value,”  Augusta  passes  a  copy  of  the  parameter  to  the  pro¬ 
cedure.  When  “by  reference,”  the  address  of  the  variable  is  passed.  A  para¬ 
meter  declared  as  “OUT”  type  is  treated  as  a  pass  by  reference  variable.  If 
the  parameter  variable  is  assigned  a  new  value,  that  new  value  is  passed  out¬ 
wards  to  the  caller.  The  program  shown  in  (a)  demonstrates  pass  by  value 
and  pass  by  reference  by  producing  the  output  shown  in  (b). 

(a) 

PROCEDURE  DEMO  IS 
X  :  INTEGER; 

PROCEDURE  BYVALUE  <  I  :  INTEGER  )  IS 
BEGIN 

PUTSTR  < “ON  ENTRY  10  BY VALUE,  I  =  ">; 

PUT I  NT  <  I  >  ;  NEWLINE; 

I:=l;  —  THIS  CHANGE  WILL  HAVE  NO  EFFECT  ON  THE  PARAMETER 

—  PASSED  TO  PROCEDURE  BYVALUE 

END; 

PROCEDURE  BYREFERENCE  <  I  !  OUT  INTEGER  )  IS 
BEGIN 

PUTSTR ("ON  ENTRY  TO  BYREFERENCE,  I  «  ">; 

PUT I NT  < I ) ;  NEWLINE; 

15=1;  THIS  WILL  CHANGE  THE  VALUE  OF  X  IN  THE  CALLING  ROUTINE 

END; 

BEGIN 
X :  =  1 00 ; 

BYVALUE ( X ) ; 

PUTSTR ( "AFTER  CALL  TO  BYVALUE,  X  STILL  =  " ) ; 

PUTINT(X);  NEWLINE;  NEWLINE; 

BYREFERENCE  «X>  ; 

PUTSTR < "AFTER  CALL  TO  BYREFERENCE,  X  IS  CHANGED  TO  =  "i; 

PUT  I NT ( X ) ;  NEWLINE; 

END; 


<b> 

ON  ENTRY  TO  BYVALUE,  1=100 

AFTER  CALL  TO  BYVALUE,  X  STILL  =  100 

ON  ENTRY  TO  BYREFERENCE,  1=100 

AFTER  CALL  TO  BYREFERENCE,  X  IS  CHANGED  TO  1 
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(Figure  1  continued  from  page  20) 

SUBTYPE 


PARAM  SUBTYPE 


TYPE  INDICATION 

DEFINED  IN  SYMBOL  TABLE 


PARAM  TYPE 

DEFINED  IN  SYMBOL  TABLE 


PRAGMA  INFO 


(Figure  1  continued  on  page  24) 


An  exit  from  a  procedure  may  be 
made  at  any  point  by  using  either  the 
EXIT  or  RETURN  statement.  To  exit 
a  procedure,  type 

RETURN; 

Functions  must  always  terminate  with 
RETURN  <  Expression>; 

where  <  Expression  >  is  the  value  of  the 
function  to  be  returned  to  the  caller.  For 
example, 

RETURN  1  +  10; 

gives  the  function  the  value  of  I  plus  1 0. 

Augusta  does  not  check  that  each 
function  contains  a  RETURN  statement. 
It  is  the  responsibility  of  the  programmer 
to  insure  that  each  function  definition 
exits  through  the  RETURN  statement. 
Note  also  that  a  function  may  only  re¬ 
turn  an  integer,  character  or  boolean.  It 
may  never  return  a  string  or  an  array. 

Arrays  as  Procedure  Parameters 

Arrays  may  be  passed  as  OUT  type 
parameters  to  procedures.  If  X  is  defined 
as 

X  :  ARRAY  (10)  OF  INTEGER; 
then  it  may  be  passed  to  a  procedure  as 
PROC2  (  @X(0)  ); 

which  passes  the  address  of  array  X.  In 
procedure  PROC2,  the  parameter  is  de¬ 
fined  as 

PROCEDURE  PROC2  (  R  :  OUT 
INTARRAY  ); 

Within  PROC2,  R  is  treated  as  an  array 
of  integers. 

INTARRAY  is  a  special  type  declara¬ 
tion,  which,  along  with  STRARRAY, 
CHARRAY  and  BOOLARRAY,  is  used 
to  pass  arrays  as  procedure  or  function 
parameters.  These  four  types  must  only  be 
used  in  a  procedure’s  parameter  declara¬ 
tions.  They  are  equivalent  to 

ARRAY  (?)  of  <type> 

where  “?”  indicates  an  undefined  array 
size,  and  <type>  is  INTEGER,  BOOLE¬ 
AN,  CHARACTER,  or  STRING. 

For  string  arrays,  the  default  string 
size  is  80  bytes.  For  a  different  size 
string,  an  optional  string  length  is  speci¬ 
fied.  For  example, 

PROCEDURE  PROC2  (  S : OUT 
STRARRAY  (120)  ); 

defines  S  as  an  array  of  strings,  where 
each  S  ( i )  is  up  to  120  bytes  long. 
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In  the  March  Issue 

Part  2  describes  how  “stack  ma¬ 
chines”  operate  and  how  they  are  used  to 
perform  expression  evaluation  and  proce¬ 
dure  calls  in  a  language  like  Augusta.  Au¬ 
gusta’s  p-machine  consists  of  about  80 
instructions,  ranging  in  length  from  a 
single  byte  up  to  7  bytes.  Each  of  these 
opcodes  will  be  described  in  detail. 
_ Mj _ 
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(Figure  1  continued  from  page  22) 
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XANADU 

Hypertext  from  the  Future 


The  Xanadu  Hypertext  System  is  a 
unified  system  for  storing  and  man¬ 
aging  certain  forms  of  information, 
namely:  bodies  of  documents.  It  is  built 
around  a  small  number  of  relatively  sim¬ 
ple  concepts: 

•  DOCUMENTS 
•  Multiple  VERSIONS  of  Docu¬ 
ments 

•  Distributed  Storage  and  Distrib¬ 
uted  Computation  —  NETWORK¬ 
ING  between  main  frames  and 
microcomputers 

•  Isolation  of  storage  functions 
from  display  functions-BACK- 
END/FRONTEND 

I  will  discuss  each  of  these  in  turn 
and  thereby  build  up  a  picture  of  what 
the  Xanadu  System  is,  what  it  does,  and 
what  makes  it  unique. 

Documents 

A  “document”  is  a  chunk  of  contigu¬ 
ous  characters  (or  other  data)  which  func¬ 
tions  in  some  way  as  a  conceptual  unit.  It 
is  simply  a  piece  of  text  which  some  user 
has  declared  to  be  a  single  thing.  It  corre¬ 
sponds  roughly  to  the  notion  of  a  “file” 
as  found  in  most  computer  systems.  Be¬ 
ware  of  this  analogy,  however,  because  it 
breaks  down  quite  thoroughly  in  the  face 
of  the  other  properties  of  the  system. 

A  document  may  contain  whatever 
the  user  decides  to  put  in  it.  While  docu¬ 
ments  will  generally  contain  text,  the  sys¬ 
tem  assumes  nothing  about  their  contents. 
Any  arbitrary  set  of  data  which  can  be 
represented  as  a  string  of  bytes  may  be 
stored  in  a  document.  Possible  documents 
include  letters,  books,  chapters  of  books, 
memos,  marginal  notes,  musical  scores, 
reports,  pictures,  computer  programs, 
maps,  diagrams,  recordings,  etc.-what- 
ever  the  user  desires  the  document  to  be. 

Each  document  stored  in  the  system 
is  assigned  a  unique  identifier  when  it  is 
created.  This  identifier  can  then  be  used 
in  later  transactions  with  the  system  to 
designate  that  particular  document.  This 
document  identifier  is  a  special  sort  of 
number  called  a  “tumbler.”  Tumblers  are 
multi-part  numbers  similar  to  those  used 
to  number  sections  of  technical  manuals 
and  to  index  books  in  the  Dewey  Decimal 
System.  For  example,  1.0.3.15  and 
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123.5.6391.0.8.1  are  both  tumblers.  They 
have  the  property  that  they  can  be  ex¬ 
panded  at  any  point,  and  it  is  therefore 
possible  to  implement  a  numbering  sys¬ 
tem  that  never  runs  out  of  precision.  This 
means  that  there  is  no  limit  to  the  num¬ 
ber  of  document  identifiers  possible  and 
therefore  no  theoretical  limit  to  the  num¬ 
ber  of  possible  documents  due  to  a  finite 
address  space. 

Since  a  document  is  a  Unear  array  of 
bytes,  we  can  refer  to  any  particular  char¬ 
acter  in  a  document  by  its  position  in  the 
document.  Thus,  by  combining  a  docu¬ 
ment’s  unique  identifier  with  a  character 
position  within  that  document,  we  can 
uniquely  address  any  character  stored  in 
the  entire  system. 

By  designating  a  particular  (starting) 
character  and  a  length  we  can  address  any 
contiguous  string  of  characters  in  the  sys¬ 
tem.  Such  a  string  is  called  a  “span.”  By 
clever  use  of  tumblers  instead  of  plain  in¬ 
tegers  to  represent  character  positions 
and  span  lengths,  it  is  possible  to  have 
spans  which  contain  whole  documents 
and  cross  document  boundaries. 

Versions 

The  Xanadu  Hypertext  System  is  a 
real  and  currently  available  product  which 
can  manage  multiple  differing  versions  of 
a  single  document.  Typically,  documents 
will  change  with  time,  as  they  are  cor¬ 
rected  or  revised.  Parallel  versions  may  be 
made,  as  when  writers  weigh  alternate 
drafts  of  a  chapter  or  when  a  computer 
program  and  its  documentation  are  main¬ 
tained  for  several  different  installations. 

Whenever  a  document  is  changed,  the 
changes  are  recorded.  The  system  remem¬ 
bers  both  the  old  and  the  new  versions 
and  can  retrieve  either  on  command. 
Thus  it  is  possible  to  retrieve  a  document 
in  the  state  it  was  in  at  any  point  in  time 
since  its  creation.  This  can  be  particularly 
useful,  for  example,  in  software  develop¬ 
ment  or  creative  writing  when  one  may 
make  false  starts  and  wish  to  back  up  to  a 
previous  state.  In  addition,  the  system 
can  indicate  the  changes  which  caused 
two  alternate  versions  to  differ.  Thus  a 
complete  “audit  trail”  through  the  his¬ 
tory  of  a  document  can  be  constructed. 
Such  a  trail  is  in  the  form  of  an  historical 
trace  tree  which  branches  whenever 
parallel  versions  are  maintained. 

In  the  general  case,  the  problem  of 
comparing  two  pieces  of  text  to  deter¬ 
mine  the  differences  between  them  is  NP- 
complete.  It  may  seem  curious  then  that 


the  Xanadu  System  is  able  to  do  this.  The 
reason  that  the  system  can  determine 
how  documents  differ  is  because  it  does 
not  compare  them.  Rather,  it  performs 
the  actual  changes  and  “remembers” 
them,  instead  of  having  a  whole  new 
document  passed  to  it  by  some  external 
editor,  as  most  systems  would  do. 

Xanadu  understands  a  simple  set  of 
editing  primitives  by  which  it  can  be  di¬ 
rected  to  make  changes  to  a  document. 
Those  are: 

•  INSERT  characters  at  some  point 
in  the  document. 

•  DELETE  characters  from  some 
point  in  the  document. 

•  MOVE  a  span  of  characters  from 
one  location  in  the  document  to 
another. 

•  COPY  a  span  of  characters  from 
one  location  in  the  document  (or 
from  anywhere  in  the  rest  of  the 
system,  for  that  matter)  to  some 
location  in  the  document. 

A  moment’s  thought  will  reveal  that 
these  operations  are  sufficient  to  perform 
then  more  complex  editing  operations. 

This  sort  of  arrangement  is  not 
unique.  However,  most  systems  which  do 
this,  such  as  Bell  Laboratories  SCCS 
(Source  Code  Control  System)  and  DEC’S 
CMS  (Code  Management  System)  merely 
keep  a  log  of  the  edit  operations  and  then 
perform  those  operations  in  chronological 
order  to  produce  the  desired  version. 
While  this  is  sufficient  in  many  cases,  it  is 
unwieldy  when  there  are  many  parallel 
branching  versions  and  it  is  costly  in 
terms  of  computational  overhead,  be¬ 
coming  more  so  as  more  and  more 
changes  are  made  to  a  document. 

In  the  Xanadu  System,  these  primi¬ 
tives  correspond  to  operations  on  the  pro¬ 
prietary  data  structures  in  which  the 
documents  are  stored.  These  data  struc¬ 
tures  tell  the  system  which  characters  are 
in  which  versions  and  in  what  order.  This 
allows  the  proper  retrieval  of  any  version 
quickly  and  efficiently.  The  historical 
traceback  facility  is  built  in  implicitly. 
To  the  best  of  our  knowledge,  the  Xana¬ 
du  System  is  the  only  system  in  existence 
able  to  manage  multiple  versions  of  data 
in  such  a  general  and  efficient  manner. 

Links 

A  “link”  is  merely  an  explicit  logical 
connection  between  one  piece  of  data 
and  another.  The  Xanadu  Hypertext  Sys¬ 
tem  supports  a  completely  generalized 
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linking  facility.  Any  body  of  text  in  the 
entire  system  can  be  linked  to  any  other 
body  of  text  in  the  system.  Links  may 
connect  text  within  a  document  or  run 
between  documents. 

Any  given  link  connects  from  one  set 
of  text  in  the  system  to  another.  The 
bodies  of  text  at  either  end  of  the  link  are 
therefore  called  the  link’s  “end-sets.” 
The  first  end-set  is  called  the  “from-set” 
and  the  second  is  called  the  “to-set.”  By 
convention  links  have  an  implied  direc¬ 
tion  from  the  from-set  to  the  to-set,  not 
surprisingly,  although  the  relationship  is 
entirely  symmetrical  and  a  link  may  be 
followed  in  either  direction. 

The  potential  contents  of  an  end-set 
are  totally  unrestricted.  An  end-set  may 
consist  of  an  unlimited  number  of  spans. 
The  characters  linked  to  or  from  need  not 
be  contiguous  or  even  in  the  same  docu¬ 
ment. 

Links  themselves  are  said  to  reside 
inside  documents,  located  in  a  separate 
logical  address  space  from  the  text.  A  link 
may  reside  in  one  document  and  link 
from  a  second  document  to  yet  a  third. 
The  location  of  the  residence  of  a  link  is 
entirely  independent  of  the  contents  of 
the  link’s  end-sets.  The  fact  that  links  are 
among  the  potential  contents  of  docu¬ 
ments  means  that  links  themselves  may 
be  linked  from  or  to,  just  as  characters 
may.  Thus  very  general  sorts  of  indirect 
structures  may  be  assembled. 

It  was  mentioned  above  that  the  end- 
sets  are  symmetric  and  only  distinguished 
by  convention.  In  fact,  a  link  may  have 
any  number  of  end-sets.  The  use  of  these 
extra  end-sets  may  vary  depending  on  the 
purpose  of  the  link.  We  have  found  it 
convenient  to  define,  again  by  conven¬ 
tion,  a  third  end-set  called  the  “three- 
set.” 

The  purpose  of  the  three-set  is  to 
designate  information  pertaining  to  the 
link  itself.  By  this  means  we  can  define 
“link  types”  which  may  in  turn  be  used 
to  determine  how  the  link  is  to  be  inter¬ 
preted.  For  example,  we  might  create  a 
“quotation  link”  type,  which  designates 
that  the  passage  linked  to  is  to  be  dis¬ 
played  in  quotation  marks  at  the  location 
linked  from.  A  “footnote  link,”  on  the 
other  hand,  might  simply  designate  that  a 
superscripted  asterisk  be  shown  at  the 
“from”  location  and  that  the  to-set  con¬ 
tents  be  displayed  only  when  the  user  so 
requests.  In  a  more  advanced  system,  the 
three-set  might  point  to  a  program  or  sub¬ 
routine  to  be  downloaded  into  the 


display  computer.  This  program  would 
then  decide  how  to  display  the  link  and 
its  end-sets.  In  any  case,  the  mechanism  is 
totally  general  and  constrained  only  by 
convention. 

There  are  very  few  systems  which  at¬ 
tempt  to  implement  a  link  facility  at  all 
like  this.  We  are  aware  of  only  one  system 
which  even  comes  close,  Englebart’s 
“Augment,”  available  on  Tymenet.  Aug¬ 
ment  implements  links  by  embedding 
code  sequences  directly  into  the  text. 
This  technique  has  a  number  of  draw¬ 
backs:  it  rapidly  becomes  unworkable 
when  more  than  a  small  number  of  links 
are  defined,  it  is  very  difficult  to  main¬ 
tain  the  bi-directionality  of  links  using 
such  a  scheme,  discontinuous  end-sets  are 
just  about  impossible,  and  embedded 
code  sequences  would  interfere  with  the 
versioning  mechanism.  As  with  versions, 
proprietary  data  structures  enable  our 
system  to  work.  Xanadu  links  are  not  em¬ 
bedded  in  the  text.  Although  links  are 
said  to  reside  in  documents,  this  is  simply 
a  means  to  allow  links  to  be  addressed 
and  thus  linked  to.  There  are  a  number  of 
tricky  problems  that  a  linkage  system 
such  as  this  presents.  In  particular, 
answering  the  question,  “What  links  con¬ 
nect  from  other  places  to  a  particular  lo¬ 
cation?”,  is  very  difficult  using  most 
conventional  schemes  of  organizing  data. 
Consider,  for  example,  the  problems 
inherent  in  assembling  such  things  as  cita¬ 
tion  indices.  Nevertheless,  we  believe  we 
have  the  general-case  solution  to  these 
problems. 

One  might  ask  what  happens  to  the 
end-sets  of  links  when  the  documents 
containing  the  characters  in  the  end-sets 
are  changed.  There  is  a  very  close  rela¬ 
tionship  between  the  linking  facility  and 
the  versioning  facility.  When  new  versions 
of  a  document  are  created,  links  are  pre¬ 
served.  It  is  possible  to  link  to  a  particu¬ 
lar  version  of  a  document,  to  all  versions, 
or  to  the  most  current  version.  Links  will 
always  point  to  the  same  text  even 
though  the  document  containing  the  text 
may  change.  For  example: 

Some  text  in 
a  document. 
Some  charac¬ 
ters  are  in¬ 
serted. 

Some  charac¬ 
ters  are  de¬ 
leted. 

[The  underlined  characters  represent  an 


end -set  of  some  link.] 

The  ability  to  maintain  links  across 
multiple  versions  of  documents  is  one  of 
the  totally  unique  and  most  powerful 
aspects  of  the  Xanadu  System.  The  prob¬ 
lems  inherent  in  doing  this  are  almost 
unimaginably  subtle,  but  we  believe  we 
have  found  the  solution. 


Multi-user 

The  facilities  of  the  Xanadu  Hyper¬ 
text  System  would  be  of  limited  utility 
if  each  user  functioned  in  isolation.  Xana¬ 
du  is  therefore  designed  to  be  a  multi-user 
system,  allowing  independent  users  to  ac¬ 
cess  and  manipulate  the  same  body  of 
information. 

Each  user  in  the  system  has  a  unique 
user  identifier  tumbler.  Each  document  in 
the  system  has  an  owner,  and  the  owner’s 
user  identifier  tumbler  comprises  one  of 
the  fields  of  the  document  identifier 
tumbler.  By  this  means  we  can  immedi¬ 
ately  determine  the  ownership  of  any 
document. 

The  owner  of  a  document  may  grant 
other  users  permission  to  access  it.  As 
with  most  aspects  of  the  Xanadu  system, 
the  access  privilege  mechanism  is  as 
general  as  possible.  Permission  to  access  a 
particular  document  may  be  granted  to 
an  arbitrary  number  of  individuals,  to 
groups  of  users, or  to  the  entire  user  com¬ 
munity.  Type  of  access  permitted  (Read, 
Write,  etc.)  is  not  a  relevant  concept  in 
the  Xanadu  System.  You  may  always  edit 
another  user’s  document  to  which  you 
have  access,  but  in  doing  so  you  create  a 
new  version  which  is  your  own  docu¬ 
ment.  By  this  means  we  can  immediate¬ 
ly  determine  the  ownership  of  any 
document. 

The  multi-user  capability  of  Xanadu 
makes  a  number  of  useful  activities  pos¬ 
sible.  For  example,  you  can  write  mar¬ 
ginal  notes  commenting  on  someone 
else’s  work.  You  write  your  comments  in 
a  document  of  your  own  and  then  link 
them  to  the  other  person’s  document. 
The  other  user  need  never  be  aware  of 
this.  It  is  like  scribbling  in  a  library  book 
without  defacing  the  book  to  the  eyes  of 
others.  As  another  example,  it  is  possible, 
using  documents,  links,  and  the  permis¬ 
sion  facility,  to  create  a  quite  sophisti¬ 
cated  “electronic  mail”  system.  By  pass¬ 
ing  a  link  to  another  user  you  can  point 
him  at  something  you  want  him  to  read. 


Here  is  some  text. 

Here  is  some  more  text. 

Here  is  me  more  text. 
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Networking 

As  the  number  of  users  on  an  instal¬ 
lation  of  the  Xanadu  System  grows 
iarger,  the  processing  and  storage  capabil- 
h\  of  even  the  largest  and  fastest  com- 
:  . i : er  will  eventually  be  used  up.  The 
nly  viable  solution  to  the  fundamental 
■  esouree  hmitations  of  centralized  facili¬ 
ties  is  distributed  processing  and  storage. 
1  he  Xanadu  System  is  designed  to  be  able 
to  grow  arbitrarily  large  without  having  a 
significant  adverse  impact  on  overall  sys¬ 
tem  performance.  It  does  this  by  allow¬ 
ing  the  system  to  spread  out  over  as  many 
machines  as  are  needed  to  support  all 
users  effectively. 

The  portion  of  the  system  which 
stores  and  retrieves  documents  and  links 
is  designed  to  be  able  to  run  simultaneous¬ 
ly  on  an  arbitrary  number  of  machines 
which  are  tied  together  in  a  network  by 
so'me  sort  of  communication  medium.  If 
a  piece  of  information  is  requested  at  one 
node  of  the  network  but  is  not  stored  at 
that  node,  the  Xanadu  software  running 
on  that  node’s  computer  sends  a  request 
via  the  network  to  the  machine  in  which 
the  information  is  stored.  This  machine  in 
turn  sends  back  the  requested  data. 

The  system  does  not  care  what  com¬ 
munications  technology  is  used,  as  long 
as  it  gets  the  bits  from  one  place  to  the 
other.  No  particular  network  topology  is 
assumed,  as  long  as  paths  exist  between 
any  nodes  which  might  wish  to  communi¬ 
cate.  Nodes  may  be  added  to  or  deleted 
from  the  network  continuously  with  the 
minimum  possible  disruption.  If  a  node  is 
deleted,  data  that  was  stored  solely  on 
!hat  node  becomes  unavailable,  of  course, 
.! n d  any  communication  paths  that  went 
through  that  node  may  need  to  be  re¬ 
routed.  possibly  delaying  some  transmis- 
>on.- 

Communications  routing  from  one 
-  ,de  to  another  is  automatic  and  implicit 
in  the  network  design.  Nodes  are  not  re¬ 
quired  to  have  full  knowledge  of  the  en¬ 
tire  network,  thus  the  network  can  grow 
without  every  node  being  informed  of 
every  change  to  the  network  topology. 

Various  optimizations  are  built  in.  If 
a  node  finds  that  it  is  being  given  fre¬ 
quent  requests  for  data  stored  on  a  dis¬ 
tant  node,  it  can  make  a  copy  of  that 
data  and  store  it  locally.  The  system  does 
not  mind  that  there  may  be  multiple 
copies  of  some  information.  If  a  request 
for  such  information  is  made,  the  system 
tries  to  get  it  from  the  closest  or  most 


quickly  accessible  source.  If  changes  are 
made  to  one  copy,  the  system  keeps 
track  All  of  this  is  accomplished  internal¬ 
ly  by  the  same  data  structures  that  man¬ 
age  all  the  other  functions  of  the  system. 

Backend/Frontend 

All  of  the  capabilities  described 
above  are  part  of  what  is  called  the 
‘backend.”  The  backend  handles  storage, 
retrieval,  versioning,  Unking  and  editing 
of  data.  However,  it  “knows”  nothing 
about  the  data,  per  se.  The  backend  is  the 
portion  which  does  all  the  “impossible” 
things.  It  contains  the  proprietary  com¬ 
ponents  which  we  have  developed. 

User  interaction— the  display  of  old 
data  and  the  acceptance  of  new  data— is 
accomplished  by  the  other  major  portion 
of  the  system,  the  “frontend.”  The  front- 
end  worries  about  whether  the  data  is 
text  or  pictures  or  music  or  whatever. 
The  frontend  decides  how  the  data  is  to 
be  formatted  for  display.  The  frontend 
knows  how  to  interface  with  various  in¬ 
put  or  output  devices. 

The  frontend  and  the  backend  com¬ 
municate  using  a  standardized  request 
and  data  transmission  protocol.  The 
frontend  sends  commands  and  data  to  the 
backend  which  responds  with  other  data 
and  status  information.  The  specifica¬ 
tions  for  this  protocol  are  free  for  the 
asking  to  anyone.  The  frontend  will,  in 
general,  be  on  a  separate  computer  which 
is  connected  to  the  backend  by  a  com¬ 
munications  line  (not  to  be  confused  with 
the  communications  lines  which  connect 
the  Xanadu  network— the  whole  network 
is  the  backend).  Any  program  which 
understands  the  protocol,  running  on  any 
computer  connected  to  the  backend,  can 
be  a  frontend.  The  frontend  need  not  be 
designed  by  us,  written  by  us,  or  pur¬ 
chased  from  us.  While  we  will  be  produc¬ 
ing  and  selling  frontends,  we  expect 
others  to  do  so  as  well. 

Frontends  may  be  general  purpose  or 
special  purpose.  Different  applications, 
different  forms  of  data,  different  dis¬ 
play  and  input  devices  and  different  user 
preferences  can  all  be  accommodated. 
For  example,  one  might  create  an  office 
automation  frontend  which  handles  text 
processing,  electronic  mail  and  project 
management  functions  through  Xanadu, 
and  does  accounting  and  database  stuff 
locally.  A  software  development  frontend 
might  use  Xanadu  to  manage  source  and 


object  code  and  documentation  and  have 
local  capabilities  for  compiling,  execut¬ 
ing  and  debugging  programs.  As  a  third 
example,  a  CAD/CAM  frontend  might 
use  Xanadu  to  store  drawings  and  docu¬ 
mentation  and  have  .  simulation  and 
modeling  functions  built  in.  All  of  these 
different  activities  can  be  accommodated 
using  the  same  backend  design— the  back¬ 
end  is  application  independent. 

Summary 

The  Xanadu  Hypertext  System  is  one 
of  the  most  powerful  systems  in  existence 
for  managing  text  in  a  micro-to-mainframe 
database  environment.  It  can  store  arbi¬ 
trary  numbers  of  documents  and  retrieve 
them  on  demand.  It  can  organize  them  by 
using  a  highly  generalized  link  facility  and 
by  allowing  (and  keeping  track  of)  mul¬ 
tiple  users  on  the  same  system,  and  allow 
those  users  to  work  with  each  other  on  a 
common  document  base.  It  can  grow  in¬ 
definitely  over  a  large  distributed  net¬ 
work  with  minimal  degradation  in  per¬ 
formance.  It  can  accommodate  almost 
any  conceivable  display  or  input  device 
or  mode  of  user  interaction  by  separating 
these  functions  into  an  independent 
frontend. 
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by  Hank  Harrison 


Stone  Age 
Computers 

6,000  Years  of 
Computing  Science 


Human  beings  are  natural  computer  users.  From  the  first 
presence  of  any  substance  or  essence  which  may  loose¬ 
ly  be  called  “mind,”  human  beings  used  computers. 
For  centuries  scientists  thought  that  humans  were  the 
only  tool-using  life  forms  on  earth,  but  the  “New  Archaeolo¬ 
gy,”  functioning  within  the  ethical  framework  set  up  by  the 
anthropologist  Franz  Boas,  and  the  highly  respected  field  of 
Ethology,  with  its  intensive  observational  techniques,  have 
shown  that  chimps  use  straws  to  pick  ants  out  of  tree  stumps, 
and  certain  bird  species  use  tools  for  nest  building.  Nor  are 
human  beings  the  only  computer- using  species  on  earth. 
It  is  difficult  to  imagine  geese  migrating  by  stellar  naviga¬ 
tion  without  some  reference  to  a  deeply  embedded  genetic 
instinct  computer  which  helps  them  judge  wind  speed,  direc¬ 
tion  and  endurance. 

The  annual  activities  of  swallows  and  butterflies,  seals, 
whales,  grunion,  even  the  lowly  potato,  all  seem  to  be  con¬ 
trolled  by  some  sort  of  internal  biocomputer.  Von  Uxeuell  and 
Tinbergen  were  awarded  a  Nobel  Prize  for  proving  that  bees 
possess  incredible  navigational  skills  and  the  ability  to  trans¬ 
late  experience  through  agitated  dance  activity. 

Prehistoric  peoples  were  zoologists.  Undoubtedly,  Ice 
Age  human  beings  made  close  and  systematic  observation  of 
animals,  as  each  species  made  use  of  its  well-developed  instinct 
computer.  Eventually  humans  realized  that  they  too  had  com¬ 
putational  abilities.  This  insight,  more  than  any  other,  seems 
to  have  acted  as  a  stepping  stone  from  which  other  human 
beings  rose  to  dominate  the  planet,  and  from  that  remote 
point  in  history  on,  for  better  or  for  worse,  the  human  being 
and  the  computer  were  married. 

The  computing  tool  was  probably  one  of  the  first  tools, 
and  the  human  use  of  external  computational  aids  is  probably 
more  than  two  million  years  old.  In  the  beginning,  stars  and 
planets,  moon  and  sun,  wind,  rain  and  thunder  dominated  the 
human  mind;  but  as  our  species  spread  through  the  various 
evolutionary  stages,  from  Homo  Robustus  the  survivor  to 
Homo  Sapiens  the  wanderer  and  finally  to  Homo  Faber  the 
manufacturer,  we  developed  an  ever-increasing  ability  to  focus 
our  own  minds  to  solve  problems. 

With  the  advent  of  computing  skills  we  learned  to  use 
wood,  wool,  crystal,  stone,  leather,  rope,  reeds,  nut  hulls,  fruit 
rinds,  sticks,  berry  juice,  sea  shells  and  bones  from  every  con¬ 
ceivable  animal,  including  the  human  animal,  to  create  knives, 
hammers  and  computational  aids  with  which  to  observe  the 
sky  and  its  complex  activities.  These  computer  tools  were 
used,  in  turp,  to  calculate  the  fertility  cycles  of  wild  and  do¬ 
mestic  herds,  to  tame  the  environment  and  to  time  plant 
rotation  cycles. 

In  prehistoric  times  each  subgroup,  tribe,  or  family  unit 
obtained  knowledge  of  other  similar  units  in  the  course  of  nor¬ 
mal  migratory  behavior.  The  structure  of  the  Paleolithic  social 
assemblage  was  supported  not  only  by  the  shared  experience 
of  natural  sign  and  symbol,  but  also  by  possession  of  an  in¬ 
credibly  long  folk  memory  stretching  back  into  primordial 
timelessness,  a  not  so  “tabula  rasa”  genetic  brain  full  of  molec¬ 
ular  legends  and  chemophysical  icon. 

Most  human  iconography  can  be  traced  to  a  non- racial, 
species- specific  set  of  images  which  relates  to  basal  survival 
realities  in  the  history  of  the  species.  Psychotropic  substances 
have  taught  us  about  expanded  consciousness  on  a  personal 
and  subjective  level  but  the  “New  Archaeology”  is  demonstrat¬ 
ing  this  molecular  mind  hypothesis  in  quantifiable  terms.  It 
seems  archaic  human  beings  were  “Transcendental  Com- 
putists.” 

One  possible  high  point  in  the  history  of  the  species  is 
referred  to  as  the  Magdalenian  epoch  —  the  age  when  tools 

Illustration  to  left:  The  Stone  of  the  Seven  Suns  -  Dowth,  Ireland. 

Illustrations:  Martin  Brennen 
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became  art  objects,  the  age  when  the  computer  was  put  to 
extensive  use,  the  age  of  the  discovery  of  the  sun  spiral.  One 
might  assume  that  this  grand  era  took  place  a  few  hundred 
years  ago,  but  guess  again.  The  Magdalenian  Age  centers  on 
10,000  B.C.!  In  other  words,  12,000  years  ago.  In  Western 
Europe,  and  elsewhere  on  this  tiny  planet  on  the  edge  of  the 
ice  sheets,  numerous  tribes  of  wandering  hunters  and  gatherers 
were  connected  to  each  other  by  common  symbols,  smoke 
signals,  navigational  skills,  arts,  crafts  and  legends. 

Each  culture  undoubtedly  made  occasional  contact  with 
drifting  sailors  lost  at  sea,  exiles,  exploratory  expeditions,  and 
merchants  of  sorts.  Each  contact  resulted  in  a  transmission  of 
technology,  linguistic  and  symbolic.  All  of  the  clans  labored 
under  the  vagaries  of  the  same  weather  conditions,  the  same 
tides,  the  same  sun  and  moon,  so  there  is  a  likelihood  that  cer¬ 
tain  basal  expressions  rose  spontaneously  at  random.  These 
multiple  tribal  clusters,  enriched  by  primordial  stories  and 
legendary  skills,  seem  to  have  been  regulated,  especially  in  the 
Middle  Stone  Age,  by  computational  instruments  of  various 
kinds,  all  geared  to  the  sky. 

Approximately  two  million  years  ago,  solar,  stellar  and 
lunar  observations  were  made  by  sand  and  stick  dials.  Odd 
radial  patterns  were  carved  in  the  sand  and  a  tall  stick  was 
erected  in  the  center  to  act  as  a  shadow  caster  or  gnomon. 
The  bush  people  of  the  Kalihari,  whose  ancestry  disappears 
into  history  and  is  so  old  as  to  be  untraceable,  still  use  a  sim¬ 
ple  stick  to  judge  the  proper  time  of  day  to  track  quarry.  The 
shadow  stick  is  magic  and  is  shrouded  in  secret  initiation. 
We  now  refer  to  these  sticks  as  sundials,  but  their  full  meaning 
and  origin  is  imperfectly  understood. 

The  period  of  history  vaguely  spanning  the  five  thousand 
years  between  10,000  and  5,000  B.C.  is  called  the  Mesolithic 
or  Middle  Stone  Age.  Here  the  Paleolithic  “Old  Stone  Age” 
art  of  computing  for  the  hunt  was  raised  to  a  religious  science 
which  was  carried  over  to  the  more  settled  Neolithic  or  “New 
Stone  Age.”  The  art  of  the  Neolithic  might  be  thought  of  as 
architectural,  except  that  the  Neolithic  Architect  retained 
certain  elements  of  Mesolithic  shamanistic  practice  which 
might  today  be  thought  of  as  psychological.  Here  at  the  Dawn 
of  Science,  magic  was  replaced  by  reason,  human  beings  began 
to  quantify  ancient  myths,  molding  them  into  permanent 
temple  monuments,  for  ritual  purposes. 

In  approximately  5000  B.C.  the  ancestors  of  the  fishing 
and  hunting  tribes,  who  had  settled  into  communities,  began 
writing  their  newly  discovered  computer  formulae  in  a  natural 
stone  language  for  the  edification  of  their  children,  and  to 
leave  messages  for  future  generations  to  decipher.  These  puz¬ 
zles  and  messages  are  written  in  a  code.  These  not -yet- fully  - 
deciphered  codes,  when  seen  in  context,  seem  identical  to 
computer  operands  and  are  obviously  connected  to  celestial 
mechanics  in  some  way. 

The  verdant  hills  and  valleys  of  Brittany,  Portugal,  Wales, 
Ireland  and  Scotland,  situated  close  to  seas  overflowing  with 
fish,  were  ideal  ecosystems  for  the  development  of  stable 
societies,  computers,  and  the  requisite  increase  in  sophistica¬ 
tion  in  celestial  observation  and  timing  techniques  that  made 
settlement  possible.  The  computer  languages,  the  symbols  and 
the  alphanumeric  codes  of  the  New  Stone  Age  derived  from 
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the  hand  sign  language  of  the  Cro-Magnon  cave  painters,  be¬ 
came  the  language  of  the  trees  of  the  hunter-gatherers  and 
finally  the  stone,  copper  and  bronze  language  variations  of 
gods  such  as  Ogmios,  the  god  of  speech,  and  Lugh  or  Ra,  the 
god  of  light.  The  ancient  language  of  shadow,  sun  and  star 
light  was  based  on  geometry  in  the  cycles  of  nature  and  is 
celebrated  in  the  stones  called  Megaliths,  which  support  and 
surround  the  vast  mounds  and  Star  Temples  dotted  across  the 
maps  of  France,  Germany,  Holland,  England,  Ireland,  Scotland 
and  North  America. 

The  Stone  Temples  and  permanent  computer  monuments 
had  a  stabilizing  influence  on  certain  societies.  These  became 
rich  and  charismatic  even  before  metal  was  introduced  to  the 
Atlantic  Rim  cultures.  The  legends  of  the  new  “agra-civitates” 
which  began  to  flower  on  the  horizon  of  the  4th  millenium 
B.C.,  a  civilization  which  Plato  called  “Atlantis,”  replaced  the 
legends  of  the  shadow  caves,  but  the  basal  iconographic  sys¬ 
tems,  the  mnenonics  of  the  ancient  computations,  were 
passed  on. 

The  eidetic  memories  of  the  Ice  Age  migrations  and  the 
Neolithic  Temple  Computers  were  dimmed  by  the  hierarchic 
growth  of  urban  life,  but  the  folk  memories  of  ritual  and 
seasonal  behavior  akin  to  the  behavior  of  certain  animals  re¬ 
mained  indelible  —  indelible  because  the  language  of  survival 
and  seasonal  prediction,  the  language  that  made  wealth  and  ur¬ 
ban  well-being  possible,  the  language  that  even  allowed  con¬ 
ceit,  was  inexorably  linked  to  the  secrets  of  the  computer 
temples.  No  matter  how  dim  or  how  repressed,  the  language  of 
the  old  gods  survived. 

A  critical  point  in  the  evolution  of  the  human  use  of  com¬ 
puters  arises  in  every  culture,  and  has  done  so  since  the  Ice 
Ages  or  earlier.  Hundreds  of  computational  experiments  from 
hundreds  of  locales  stand  as  evidence.  The  Pyramids,  Machu 
Picchu,  the  Yucatan,  Stonehenge,  the  Ziggurats  of  Babylon, 
the  Gothic  Cathedrals  and  the  Masonic  ground  plan  of  Paris  or 
Washington,  DC,  are  all  products  of  computational  pre¬ 
planning  at  different  moments  in  history,  computational  abili¬ 
ties  which  took  celestial  mechanics  into  account. 

Anyone  with  enough  air  fare  and  gumption  can  visit  three 
of  these  ancient  and  most  ingenious  computers  on  their  next 
visit  to  Ireland.  These  three  giant  stone  mounds,  located  along 
the  River  Boyne,  four  miles  inland  from  the  Irish  Sea,  are  un¬ 
doubtedly  among  the  most  magnificent  computers  in  the 
world.  They  are  older  than  the  Pyramids  of  Egypt,  they  are 
more  beautifully  situated  than  the  Oracle  at  Delphi  and  are 
more  dynamic,  more  relational,  and  richer  in  culture  than 
Stonehenge. 

The  three  mounds  of  Brug  na  Boinne  are  located  less  than 
one  mile  from  each  other  and  were  built  in  different  stages  at 
different  times,  from  at  least  4200  B.C.  to  3200  B.C.  — 
Knowth  and  Dowth  being  the  oldest.  New  Grange  the  young¬ 
est  —  all  according  to  a  preconceived  plan,  a  mysterious  build¬ 
ing  plan  that  took  one  thousand  years  to  execute,  a  building 
plan  that  was  carved  into  the  stones  only  after  the  final 
mound,  the  third  of  the  triple  complex,  was  constructed! 

The  continuity  of  building  design  in  Irish,  Welsh  and 
French  Atlantic  Megalithic  structures  indicates  that  the  Star 
Temples  of  the  New  Stone  Age  were  used  as  almanacs  by 
any  tribe  with  similar  values,  and  were  therefore  very  real 
computers.  It  should  be  stressed  that  these  Computer  Temples 
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sunlight  apd  shadow,  the  codes  are  carved  deeply  into  massive 
stones,  These  stones  were  purposefully  put  in  place  to  express 
something  larger  than  the  carvings'; themselves,  Brennan  claims 
#'the  Megaliths  in  the  Atlantic  fpheffe  pre  relational.  Twoig 
views  tsaft  of  the  Attest' as  separate  entities 
Neither  point  tm  been  proved  at  this  time,  but  certain  simi¬ 
larities  do  exists  H| 

from  material  collected  by  these  scholars,  and  a  growmg 
number  of  other  reseat  chcrs,  it  is  easy  to  speculate  that  the 
sun  ahd  moon  were  captured  twenty-four  hours  each  day  ami 
that  the  entire  complex  must  be  thought  of  as  an  observatory. 

'  The  markings  on  the  Megaliths  tall  statistically  into 
groups,  the  continental  carvings  being  somewhat  more  eerie 
and  perhaps  more  afi.cient.  the  Irish  groupings  are  somewhat 
■■more  geometric^  -  Although  clparly.  both  subsets  are  derived 
from  '«f  older,  perhaps  legendary,  master  toot,  A  mat  Attan- 
fic  language  which  frankly  we  may  never  see  first  hdnd,  ex¬ 
cept  through  these  subsets.  ^ 
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Software  Review 

JRT  Pascal:  Another  Look 


JRT  Pascal  is  not  quite  as  bad  as 
Dave  Cortesi  claims  and  deserves  a  spirited 
defense.  It  is  possible  that  Cortesi  failed 
to  read  the  manual  carefully,  and  did  not 
make  the  effort  to  struggle  through  the 
admittedly  tough  first  few  lines  of  orig¬ 
inal  code.  Instead,  he  took  the  easy  way 
out  and  savaged  the  product  on  the  du¬ 
bious  point  of  language  standard  and 
portability,  which,  frankly,  no  commer¬ 
cial  Pascal  has. 

I  submit  that  JRT  Pascal  is  not  only 
a  bargain,  but  an  absolute  steal.  I  enjoyed 
its  good  fit  to  CP/M  and  departure  from 
some  of  the  more  irksome  features  of 
standard  Pascal  so  much  that  I  sent  my 
money  in  for  my  own  disk  and  manual 
after  I’d  received  a  pirated  copy. 

JRT  seems  to  meet  business  program¬ 
ming  needs  better  than  a  Jenson  and 
Wirth  standard  Pascal  can.  Due  to  the 
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CALL  function  and  SYSTEM  functions, 
it  works  in  harmony  with  CP/M  and  fully 
makes  use  of  its  facilities. 

The  real  standard  is  CP/M,  deter¬ 
mined  not  by  theory  but  by  market  need. 
Where  CP/M  goes,  so  goes  JRT.  That  will 
be  plenty  for  most  programmers.  An 
additional  benefit  of  JRT  is  that  royalties 
are  not  charged  for  the  run-time  EXEC 
needed  to  run  intermediate  code.  This 
means  that  you  may  distribute  the  EXEC 
free  of  charge  to  your  customers  along 
with  your  compiled  JRT  INT  files. 

The  declaration  of  a  character  vari¬ 
able  as  “string!  1]”  would  have  allowed 
Cortesi  to  sample  single  characters  with¬ 
out  carriage  returns.  Granted  this  is  not 
standard.  But  consider  the  alternatives 
the  language  processors  offer  —  Fortran  - 
80  and  PL/I-80  coming  to  mind  —  where 
a  read-character  routine  must  be  written 
in  assembly  language  and  linked  in  each 
compile-time  cycle.  I  wrote  a  test  pro¬ 
gram  that  uses  the  string!  1  ]  declaration 
as  well  as  the  concatenation  features  so 
quickly  dismissed  by  Cortesi  to  produce  a 
SuperCalc-style  data  entry  module.  It 
went  together  quickly  and  worked  well  — 
the  bottom  line  on  any  language.  I  also 
wrote  JRT  Pascal  programs  that  success¬ 
fully  used  sequential  character  and  line 
delimited  I/O,  and  fixed  record  sequential 
and  random  I/O  (with  no  padding  of  odd- 
length  records).  The  classic  Wirth  recur¬ 
sive  quicksort  was  implemented  quickly 
from  the  book  Algorithms  +  Data  Struc¬ 


tures  =  Programs. 

JRT  has  no  exclusive  on  compiler 
failure.  Try  Pascal  M/T,  or  UCSD  Pascal, 
or  sample  Digital’s  PL/I-80  version  1.3, 
or  Microsoft’s  Fortran  compiler.  These 
latter  two  occasionally  blow  up  if  a  mis- 
punctuation  distorts  block  structure. 
Digital’s  PL/I-80  will  on  occasion  deliver 
ten  error  messages  for  only  one  error. 
Mike  Lehman’s  Pascal  MT-Plus  in  its 
initial  Version  5  costing  $325.00  plus 
$100.00  for  each  upgrade  had  sequential 
file  I/O  problems  and  inconsistently  exe¬ 
cuted  console  I/O  from  one  version  of  the 
read  statement  to  the  next.  Are  any  of 
the  above  compilers  “bad”?  I  think  not. 
So  what  do  you  do  when  these  bugs 
show?  You  learn  to  type  the  code  in 
right,  a  process  which  Cortesi  states  he 
didn’t  take  the  trouble  to  do!  Bottom 
line:  JRT’s  compiler  is  average  on  error 
handling,  but  better  than  average  on  ver¬ 
bosity  when  it  catches  the  right  error. 

JRT’s  string  handling  and  less-than- 
rigid  typing  are  extremely  useful  in  busi¬ 
ness  programming,  particularly  in  the  pro¬ 
duction  of  standard-length  fields,  and 
formatting.  I  particularly  like  the  ability 
to  use  the  statement  “write(astring:32)” 
and  have  the  ability  to  set  a  string  of 
characters  in  a  fixed-length  field.  I  also 
find  the  ability  to  assume  the  occurrence 
of  truncation  or  padding  of  unequal 
length  structures  in  assignment  a  great 
time  saver.  The  very  popular  data  base 
language,  DBASEII,  does  this,  allowing 
flexibility  in  resizing  and  conversion  of 
existing  data  bases  and  nobody  is  com¬ 
plaining.  So  why  should  it  be  a  point  of 
criticism  for  JRT  Pascal?  Using  yet 
another  example,  M  BASIC  and  CBASIC 
are  great  commercial  successes  because 
they  get  the  job  done.  So  do  we  criticize 
them  for  being  non-standard  BASIC? 
Nope.  We  make  use  of  them,  moaning 
and  bitching  all  the  while  but  cranking 
out  fabulous  things,  as  demonstrated  in 
prior  issues  of  Dr.  Dobb 's  Journal. 

Why  should  you  have  to  put  up  with 
conceptually  elegant  file  I/O  concepts 
that  sprang  forth  in  the  days  when  tape 
was  the  leading  form  of  mass  storage,  just 
to  adhere  to  the  Pascal  standard?  I  frank¬ 
ly  get  tired  of  writing  hundreds  of  lines  of 
library  code  in  “standard”  Pascal  to  pro¬ 
duce  commonly  used  forms  of  file  access. 
One  of  JRT’s  few  shortcomings  in  this 
area  is  that  it  failed  to  include  a  non¬ 
standard  equivalent  to  BASIC’s  line  input 
statement. 


A  better  starting  point  for  Cortesi’s 
critique  would  have  been  a  comparison  to 
the  CBASIC  compiler/interpreter.  Both 
CBASIC  and  JRT  Pascal  have  similar  in¬ 
tent.  They  are  languages  oriented  to  busi¬ 
ness  programming.  CBASIC  leads  in  age 
and  maturity  and  thus  has  fewer  bugs  in 
it.  CBASIC’s  compilation  speed  is  about 
2  to  2.5  times  faster  than  JRT’s.  In  turn, 
JRT’s  compilations  run  2  to  2.5  times 
faster  than  those  in  PL/I-80  or  Pascal/MT. 

JRT  Pascal  beats  CBASIC  in  both 
integer  and  BCD  real  math  processing 
speed  and  flexibility  of  data  structures.  It 
interfaces  to  the  CP/M  system  and  assem¬ 
bly  language  modules  more  easily  than 
CBASIC.  My  benchmark  tests  of  JRT 
against  BASIC-80  in  double- precision 
mode  and  PL/I-80  (a  native  code  com¬ 
piler)  in  fixed  decimal  mode  give  JRT  a 
small  edge  in  addition  and  multiplication 
and  only  a  1 .5  -to- 1  disadvantage  against 
PL/I-80  for  division.  JRT’s  results,  by  the 
way,  are  decimally  correct.  Like  CBASIC, 
JRT  Pascal  uses  14-digit  precision  float¬ 
ing  decimal  math. 

CBASIC’s  intermediate  files,  given 
an  identical  program,  seem  to  be  a  tad 
smaller  than  JRT’s.  JRT’s  dynamic  over¬ 
lay  manager  and  storage  recovery  tech¬ 
niques  give  it  the  edge  in  program  modu¬ 
larity,  allowing  separate  intermediate  files 
for  generalized  subroutines  as  well  as 
major  subprogram  modules.  Either  lan¬ 
guage  allows  you  to  create  massive,  com¬ 
plex  systems  of  subprograms  that  use  a 
minimum  of  disk  space. 

On  the  other  hand,  the  bugs  in  JRT 
are  real,  but  you  can  write  around  them. 
If  you’re  good.  It’s  not  a  start-up  tool, 
but  I  believe  Cortesi  overreacted.  Inci¬ 
dentally,  I  found  a  number  of  bugs  no¬ 
body  has  mentioned  as  yet. 

I  couldn’t  get  the  %NOLIST  com¬ 
piler  directive  to  work,  so  it  listed  code 
on  the  console  as  it  compiled  (which 
probably  slows  it  down  somewhat).  JRT 
wouldn’t  read  record  zero  in  random  I/O 
mode,  using  the  RRN  (relative  record 
number)  form  of  random  access.  The 
latter  problem  was  written  around  by 
using  JRT’s  unique  RBA  (relative  byte 
address)  random  I/O  feature  to  access 
record  0.  RRN  and  RBA  may  be  used  in¬ 
terchangeably  without  closing  and  re¬ 
opening  files,  which  leads  to  marvelous 
possibilities  for  constructing  files  with 
built-in  indexes.  Tyson  is  aware  of  the 
RRN  =  0  problem  and  is  working  on  it. 
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Some  of  the  problems  that  occurred 
in  initial  shipments  of  JRT  packages  re¬ 
sulted  from  the  fact  that  INT  files  com¬ 
piled  with  the  Version  I  compiler  were 
inadvertently  placed  on  the  Version  II 
distribution  disks.  Version  I  files  are  not 
compatible  with  the  Version  II  execu¬ 
tive.  Tyson,  to  my  knowledge,  has  been 
making  good  on  the  bad  disks  that 
slipped  out.  My  first  copy  of  JRT  was 
“pirated,”  which  is  okay  with  Tyson  be¬ 
cause  I  received  it  as  a  gift.  Liking  it  very 
much,  I  sent  in  the  $29  for  my  own  copy 
and  received  a  disk  with  the  correct  INT 
files,  which  I  pirated  right  back  to  the 
guy  who  gave  me  the  original  pirated 
copy. 

JRT’s  implied  claim  that  all  compo¬ 
nents  of  his  system  will  run  in  56K  is  not 
entirely  true.  It’s  true  of  the  compiler  it¬ 
self,  but  not  true  of  JRTASM,  an  assem¬ 
bler  that  creates  either  INT  or  COM  files. 
Fortunately,  Tyson  has  included  a  pro¬ 
gram  called  CONVERTM  that  will  con¬ 


vert  assembled  Microsoft  or  RMAC 
REL  files  into  INT  files  that  may  be 
run  as  callable  procedures.  One  of  the 
subroutines  called  by  CONVERTM, 
testbit.asm,  does  not  appear  on  the  distri¬ 
bution  disk  as  an  INT  file.  So,  you  can’t 
use  CONVERTM  either.  My  solution  was 
to  find  a  full  64K  machine  and  use 
JRTASM  to  assemble  testbit.asm  into  an 
intermediate  file.  As  the  output  is  only  1 
CP/M  sector  long,  I  dumped  it  with  DDT, 
took  the  hardcopy  home,  patched  it  back 
into  DDT,  and  then  saved  it  as  TESTBIT. 
INT.  Now  CONVERTM  runs  and  I  can 
use  relocatable  REL  files  in  my  58K  sys¬ 
tem.  It’s  a  long  way  around,  and  I  hope 
Tyson  still  reads Dobb’s. 

PS 

After  I  wrote  the  above  critique  I  ran 
a  critical  pass  program.  The  FOR  INDEX= 
1-4  statement  hung  after  the  second  itera¬ 
tion  of  output  to  screen  and  instead  sent 
the  output  to  the  printer,  which  was 


switched  on  at  the  time.  This  is  another 
potentially  real  problem  for  Tyson  and  he 
should  really  get  a  handle  on  if  soon  as 
the  output  not  only  goes  to  the  printer 
but  takes  the  keyboard  over  there  too. 
Somehow  I/O  byte  location  03  hex  got 
modified  to  01  hex.  The  program  is  not 
error  free  yet,  but  at  30  bucks  I,  for  one, 
ain’t  complaining.  I  do,  on  the  other 
hand,  sympathize  with  those  who  have 
had  trouble  with  any  of  these  problems 
.  .  .  someday  they  will  be  ironed  out. 


Rebuttal 

by  D.E.  Cortesi 


Dan  Hunt  seems  to  be  making  two 
main  points:  (1)  language  standards 
aren’t  important,  other  compilers  violate 
the  Pascal  standard,  and  anyway  JRT’s 
nonstandard  features  are  useful,  so  they 
shouldn’t  be  criticized;  and  (2)  JRT  Pas¬ 
cal  has  lots  of  bugs,  but  so  do  other  prod¬ 
ucts  and  anyway  a  good  programmer  can 
code  around  most  of  them.  I  don’t  buy 
either  of  these  propositions,  and  I’d  like 
to  explain  why. 

1  don’t  think  I  have  to  work  very 
hard  to  defend  the  idea  of  language 
standards.  Think  about  the  difficulty  of 
moving  even  a  simple  BASIC  program 
from  a  TRS-80  to  an  Atari.  Compare  that 
to  the  ease  of  moving  a  FIG-FORTH 
program  between  any  two  machines.  The 
benefits  of  an  effective  standard  are  ob¬ 
vious.  If  Hunt  really  doesn’t  understand 
this  now,  he  will  begin  to  appreciate  it 
when  he  decides  to  upgrade  to  a  16-bit 
system.  If  he  is  lucky,  JRT  Systems  will 
have  a  new  compiler  for  the  system  he 
wants  to  move  to  (if  he’s  very  lucky,  it 
will  be  compatible  with  their  old  one).  If 
they  haven’t,  Hunt  will  find  himself  re¬ 
writing  all  his  neat  programs.  He  won’t 
have  looked  at  them  in  months;  the 
wasted  effort  and  time  will  be  quite  pain¬ 
ful.  And  if  he  has  written  programs  for 
pay,  what  are  his  customers  or  employers 


to  do  when  they  want  to  upgrade? 

I  noted  in  my  review  that  Pascal  im¬ 
plementors  are  often  forced  to  extend  the 
language.  There  is  a  big  difference  be¬ 
tween  extending  Pascal  (with  new  prede¬ 
clared  types  and  functions)  and  altering  it 
with  gratuitous  twiddles  of  the  core  lan¬ 
guage  as  defined  by  Wirth  (and  by  ISO). 
The  difference  is  this:  so  long  as  the  core 
is  implemented  correctly,  a  program  that 
uses  only  those  standard  features  can  be 
ported  to  any  compiler  that  also  imple¬ 
ments  the  core  language.  That  includes 
many  systems  besides  8-bit  CP/M.  CP/M 
is  definitely  not  “the  standard”;  a  pro¬ 
gram  in  standard  Pascal  can  run  on  UNIX 
and  TOPS  and  MSDOS,  on  8086s  and 
6800s  and  370s  and  VAXes.  I  did  not 
criticize  JRT  Pascal  for  its  extensions 
(many  of  which  are  useful),  but  for  its 
completely  unnecessary  alterations  of  the 
core  language. 

Now,  as  to  the  product’s  bugginess. 
Nothing  in  JRT’s  ads  or  manual  indi¬ 
cated  that  it  was  being  sold  for  hackers 
only.  It  is  sold  as  a  finished,  professional 
product,  ready  for  use  by  anyone  who 
knows  Pascal.  That’s  the  standard  against 
which  I  measured  it,  with  the  results  I 
described.  I  wasn’t  reviewing  any  other 
compiler,  I  was  reviewing  this  one.  I  re¬ 
ported  the  large  number  of  compiler 


crashes  that  turned  up,  a  much  larger 
number  than  I  could  ever  tolerate  in  an 
important  software  tool. 

I  will  accept  Hunt’s  assertion  that  I 
could  have  coded  around  the  problems. 
But  I  must  ask,  why  should  /  have  to ? 
Maybe  Hunt  feels  that  when  a  compiler 
crashes,  it  has  presented  him  with  a  fun 
riddle,  a  pleasant  chance  to  exercise  his 
wits.  To  me,  a  compiler  crash  is  an  infuri¬ 
ating  interruption  in  the  flow  of  my  work. 
To  Hunt,  there’s  nothing  wrong  with 
having  to  recode  and  recompile,  maybe 
several  times,  in  order  to  coax  the  com¬ 
piler  into  doing  its  job.  To  me,  that  sort 
of  thing  is  a  total  waste  of  my  time, 
which  is  all  too  limited  as  it  is. 

But  okay,  I  will  revise  my  conclu¬ 
sions.  If  you  write  programs  only  for 
your  own  use,  and  if  you  expect  never, 
ever,  to  move  to  different  hardware,  and 
if  you  enjoy  puzzling  out  and  coding 
around  compiler  failures,  then  you  will 
find  JRT  Pascal  an  acceptable  product.  If 
you,  like  me,  want  the  ability  to  write  (or 
use)  portable  code,  or  if  you  believe  as  I 
do  that  a  compiler  should  compile,  regu¬ 
larly  and  reliably,  then  you  will  find  JRT 
Pascal  Not  Acceptable  just  as  I  did. 
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Small-C  Compiler,  v.2 

Listing  One  (Part  five  continued) 
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b  sign(nbr)  lnt  nbrl  ( 

6  if(nbr>0)  return  li 

7  else  lf(nbr==0)  return  Ol 

8  else  return  -1 1 
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whi 1 e( sz  )  < 

str[  — 5  7  )  =  (  nbr%  I  O' O'  )  i 
i f ( ( nbr=nor/ 10 )==0)  breakl 


CP/M  EXCHANGE 


by  Gene  Head 

I  can  now  supply  many  standard 
modem  programs  on  disk.  All  source 
programs  are  configured  for  serial  modem 
connected  to  an  IMSAI  MIO  (Multiple 
I/O).  [Editor’s  note:  We  still  haven’t 
found  anything  better  at  twice  the  price. 
These  MIO's,  however,  no  longer  seem  to 
be  available  from  Fischer -Frietas- IMSAI 
in  Oakland,  California.] 

I  also  have  a  hot  DIR. ASM  program 
available  which  will  replace  simple  DIR  in 
the  CCP.  You  can  name  it  DIR.COM  or 
DIR.CMD.  This  program  is  quite  similar 
to  the  LST  program  in  the  new  CP/M86. 
It  displays  the  directory  after  an  Alpha 
sort  and  displays  information  in  the 
footer  much  as  if  you  had  used  ST AT 
*.*.  The  footer  line  looks  like  this: 

Drive:  Xn  Files  (Number  requested) 
Bytes:  nK  (Used  for  each  file) 

With  a  little  tooling  around,  one 
could  get  the  actual  keystroke  sequence 
down  to  one  or  two  characters  and  a  car¬ 
riage  return. 

The  entire  listing  will  appear  as  an 
article  in  DDJ  soon  but  in  the  meantime 
if  you  want  a  listing  or  any  of  the  Modem 
programs,  send  the  stamps  sufficient  to 
cover  postage,  your  disk  and  mailer  and 
a  cover  letter  along  with  five  bucks,  and 
I  will  ship  the  material  off  right  away 
first  class.  My  address  is: 

Gene  Head 
Headquarters 
2860  N.W.  Skyline  Drive 
Corvallis,  Oregon  97330 

Or  call  my  RCP/M  system: 

RCP/M  Exchange  System 
Ringback  9:00  a.m.  —  9:00  p.m. 
Monday  —  Friday  only  , 

(503) 758-8408 
300  baud  only 

Paul  Pennington  (2912  Palmetto 
Drive,  Martinez,  GA  30907)  says  he  has  ! 
won  the  battle  of  MODEM 7  vs.  the  Heath 
89/90  computer.  Send  him  a  disk,  a 
mailer,  and  five  dollars  to  cover  postage 
and  his  effort,  and  he  will  return  the 
di  k  with  MODEM7  configured  for  the 
Heath  and  several  documentation  files 
that  should  make  modem  communica¬ 
tions  easier.  Paul  can  handle  any  Heath 
five-inch  format  as  well  as  SSSD  IBM 
eight-inch  disks  (CP/M  not  HDOS). 

H.  G.  Heard  (50  Skywood  Way, 
Woodside,  CA  94062)  wants  help  inter¬ 


facing  a  TRS-80  (port  B)  with  an  Ander¬ 
son/Jacobson  ADAC  242  modem  and  the 
MODEM7  software  package. 

John  Beal  (15  Dumont  Round,  Belle 
Mead,  NJ  08502)  is  looking  for  any 
experienced  CP/M  users  that  he  can  meet 
in  his  area  for  software  and  hardware 
assistance. 
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OF  INTEREST 


by  Michael  Wiesenberg 


Nuts  and  Bolts 

“MICROMINT  MPX-16  takes  on  the 
IBM  PC,”  says  the  press  release  announc¬ 
ing  the  $1200  (in  quantities  of  100) 
single -board  computer  system  fully  com¬ 
patible  with  hardware  peripherals  and 
software  for  the  IBM  PC.  It  has  a  5MHz 
8088  with  20-bit  addressing  that  allows 
up  to  1Mb  of  memory.  An  8087  math 
coprocessor  and  hard  disk  drive  can  be 
added.  The  board  comes  with  256K 
RAM,  two  serial  and  three  parallel  ports, 
double-density  floppy  disk  controller, 
and  five  expansion  slots.  It  uses  CP/M- 
86,  but  MS-DOS  and  “other  software” 
are  coming  “soon.”  The  CP/M-86  BIOS 
is  in  EPROMs  on  the  board.  All  you  add 
are  power  supply,  serial  terminal,  and  one 
floppy  drive.  Reader  Service  No.  205. 

For  high -resolution  color  graphics 
processors,  monitor,  and  printer,  I’m  not 
sure  what  “low-cost”  and  “affordable” 
(according  to  the  release)  mean,  but  the 
prices  certainly  are  coming  down.  Vec- 
trix  Corporation’s  8088-based  VX128 
has  672-by-480  resolution,  high-speed 
three-dimensional  image  generation, 
graphics  commands,  128K  graphics  RAM, 
three-bit  planes,  and  eight  colors  for 
$1995  (less  than  half  that  of  the  compe¬ 
tition,  they  claim),  while  the  VX384  has 
384K  graphics  RAM,  nine-bit  planes,  and 
displays  512  simultaneous  colors  from  a 
palette  of  16  million  for  $3995.  Both 
translate  commands  from  most  micros 
or  minis  (at  300  to  19.2K  baud  from  ser¬ 
ial  or  8 -bit  parallel  port),  have  a  NEC 
PD7220/GDC  chip  that  generates  high¬ 
speed  lines  and  arcs  in  many  dot  and  dash 
patterns  with  1600-nanosecond  pixel 
update,  video  output  in  separate  or  com¬ 
bined  horizontal  and  vertical  or  sync  on 
green,  40  rows  of  96  alphanumeric  char¬ 
acters  in  a  5-by-9  matrix  with  descen¬ 
ders,  software  for  point,  line,  arc,  and 
polygon  primitives  in  two  and  three 
dimensions,  solid  polygons  with  pattern 
fill,  various  3-D  commands,  character 
generation  with  slant,  magnification,  and 
spacing  parameters,  and  bidirectional 
DMA  access  to  graphics  RAM.  The  13- 
inch  high -resolution  RGB  VXM  monitor 
costs  $1295,  as  does  the  IDS  Prism  color 
printer.  The  printer  can  be  accessed 
without  affecting  the  display.  Both 
graphics  processors  can  be  commanded 
from  high-level  and  assembly  languages. 
Interfaces  are  included  for  light  pen  and 
keyboard  add-ons.  Reader  Service  No. 
207. 

The  Compu/time  Universal  Floppy 


Disk  Controller  I  board  from  GSR  Com¬ 
puters  connects  up  to  four  drives  in  any 
combination  of  554-  or  8 -inch  ANSI 
standard  interfaces  or  both.  It  reads  and 
writes  disks  of  different  sizes  and 
formats,  from  554-inch,  40-track,  single¬ 
sided,  single -density  to  96-track,  double¬ 
sided,  double-density  with  512  bytes  per 
sector,  and  8 -inch,  single-sided,  single¬ 
density  to  double-sided,  double-density 
with  1024  bytes  per  sector.  Since  the 
source  listing  of  the  format  program  is 
included,  you  can  also  create  your  own 
formats.  In  addition  to  the  board,  you  get 
a  manual  and  8-inch,  single-sided,  single¬ 
density  CP/M  disk  with  Monitor/BIOS 
and  disk  formatter  source  listings.  The 
UFDC-1,  assembled  and  tested,  costs 
$325.  A  kit  is  $295,  and  bare  board  is 
$60.  Add  $5  shipping  and  handling,  and 
residents  of  New  York  State  add  854% 
sales  tax.  Reader  Service  No.  209. 

Hewlett-Packard  now  has  two  new 
personal  computers  being  sold  through 
retail  computer  dealers.  The  HP  Series 
100  Model  120  has  the  power  of  the  HP 
125  in  a  smaller  package.  It  is  a  CP/M- 
based,  8-bit,  dual -processor  computer 
with  64K  main  memory,  16K  screen 
display  memory,  and  32K  fixed  memory 
for  internal  functions.  It  has  screen- 
labelled  softkeys.  Available  software  in¬ 
cludes  WordStar,  SpellStar,  MailMerge, 
VisiCalc,  CONDOR  DBMS  and  report 
generators,  Series  100  WORD  word 
processing  (HP’s  implementation  of  Lexi- 
soft’s  Spellbinder),  Graphics,  DSN/Link, 
and  BASIC.  The  $2275  price  includes 
processor,  display,  64K  memory,  and 
keyboard.  The  HP  Series  200  Model 
16  is  HP’s  first  16-bit  personal  computer 
to  be  sold  through  dealer  channels.  Its 
processor  is  the  Motorola  8MHz  16/32- 
bit  68000.  Built-in  graphics  are  standard, 
as  are  five  user-definable  softkeys  (a 
number  doubled  with  the  shift  key), 
an  80-column-by-25-row,  300-by-400- 
pixel  display,  and  a  rotary  control  knob 
for  fast  editing,  cursor  movement,  analog 
instrument  control,  and  other  linear  input 
applications.  Three  language  systems  are 
available:  BASIC,  HPL,  and  Pascal. 
Third-party  vendors  offer  others,  includ¬ 
ing  FORTH.  UNIX  should  soon  be 
available,  and  CP/M  is  also  planned.  The 
Model  16  can  be  linked  with  other  HP 
desktop  computers  in  a  network  that 
shares  disk  drives  and  printers.  Base  price 
is  $3650,  for  processor,  display,  128K 
memory  (expandable  to  768K),  and 
keyboard.  Both  models  have  a  tilt-and- 


swivel  accessory  for  $110.  Available 
peripherals  for  both  systems  include  dual 
354-inch  micro-floppies  with  270K  per 
disk  for  $1775  (or  one  drive  for  $1200) 
and  one  micro-floppy  drive  plus  4.6  Mb 
Winchester  for  $4975.  HP  also  offers  a 
daisy-wheel  printer,  the  HP  2602A,  for 
$1950.  Reader  Service  No .  211. 

Memory  Merchant’s  64K  static  RAM 
S-100  memory  board  operates  at  6MHz 
or  greater,  has  four  independently  ad¬ 
dressable  16K  blocks,  uses  150ns  16K 
(2K  x  8)  CMOS  static  RAMS,  has  a  two- 
year  warranty  and  costs  $629.  Reader 
Service  No.  213. 

Add  intelligent  text  and  graphics 
printing  capabilities  to  your  Apple  II 
or  HI  with  PKASO  (is  that  a  pun?) 
from  Interactive  Structures  Inc.  Dump 
any  screen,  print  in  26  shades  of  gray, 
use  your  own  or  predefined  characters, 
and  draw  with  both  high-  and  low- 
resolution  graphics  on  many  dot  matrix 
printers.  Interface,  software,  cable,  manu¬ 
al,  and  demo  disk  cost  $165.  Reader  Ser¬ 
vice  No.  215. 

Do  you  have  five  computers  and  one 
printer?  How  about  five  printers  and  one 
computer?  Handle  either,  and  other 
permutations,  with  MultiSpool  from 
Digital  Laboratories  Inc.,  a  buffered 
multiport  spooler  with  a  Z80  processor, 
64 K  DRAM,  8K  ROM,  4  UART  channels, 
various  configurations  of  parallel  8 -bit 
ports  and  serial  ports,  and  status  LEDs, 
priced  from  $595  to  $995,  depending 
on  configuration.  Reader  Service  No. 
217. 

Bits  and  Bytes 

Want  to  do  word  processing  on  your 
VIC-20  or  Commodore-64?  Quick 
Brown  Fox  can  be  used  even  on  the  VIC- 
20’s  22-column  display.  For  $65  you  get 
line  and  global  editing,  text  manipulation, 
boilerplating,  tab  and  margin  settings, 
right  justification,  proportionally  spaced 
printing,  and  automatic  reformatting  of 
edited  text.  Reader  Service  No.  219. 

Elektrokonsult  offers  disk  utilities 
for  the  Osborne -1  that  avoid  data  loss. 
DTEST  tests  for  bad  sectors,  and  col¬ 
lects  them  in  a  write-protected  file. 
UNERA  recovers  erased  files.  DDUP 
automatically  recovers  files  with  damaged 
sectors.  DDUMP  examines  and  patches 
data  on  any  sector,  enabling  you  to  repair 
crashed  disks  and  recover  lost  data.  Each 
program  costs  $29.95,  or  you  can  get  all 
four  for  $99.95.  Add  $8  for  air  shipment 
from  Norway.  Reader  Service  No.  221. 
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Want  to  use  your  IBM  PC  to  talk 
to  mainframes?  Blue  Lynx  from  Tech- 
land  Systems  Inc.,  a  3270  emulation 
package,  currently  emulates  an  IBM  3276 
controller/display  under  SDLC  protocol 
and  will  soon  offer  bisync  protocol  and 
IBM  3278  emulation  for  connection  by 
coaxial  cable  to  3  274 -like  cluster  control¬ 
lers.  What  you  get  is  a  plug-in  communi¬ 
cations  card  and  software  on  floppy  disk 
for  S690.  Reader  Service  No.  231. 

Another  telecommunications  pack¬ 
age  from  Century  Systems,  called  Com- 
Crypt,  combines  computer  communica¬ 
tions  with  encryption  and  decryption  to, 
send  and  receive  CP/M  files  with  com¬ 
plete  security,  using  a  proprietary  encryp¬ 
tion/decryption  technique.  ComCrypt 
provides  users  of  the  CP/M  operating  sys¬ 
tem  with  security  features,  including  an 
encrypted  “chat”  mode,  and  helps  to 
prevent  unauthorized  “eavesdropping”  on 
computer  communications.  It  operates 
over  regular  telephone  lines  or  direct 
wire  between  computers.  The  installa¬ 
tion  program  supports  a  large  number  of 
common  terminals.  To  use  ComCrypt 
on  your  machine  requires  a  Z80,  CP/M 
version  2.0  or  later,  a  24  x  80  terminal 
with  clear  screen  and  addressable  cursor, 
and  $250.  Reader  Service  No.  233. 

The  mbp  COBOL  (ANSI  74)  compil¬ 
er  from  mbp  Software,  for  several  8086- 
based  systems,  including  CP/M-86,  MS- 
DOS,  and  iRMX-86,  with  MP/M-86  and 
OASIS- 16  coming  soon,  generates  native 
code.  It  automatically  corrects  simple 
syntax  errors.  Included  in  the  $500  price 
is  a  45K  run-time  library.  Reader  Service 
No.  235. 

The  ZAS  Z-8000  Software  Develop¬ 
ment  Package  from  Western  Wares  runs 
on  any  CP/M-80  system.  The  relocatable 
macro  assembler  supports  both  segment¬ 
ed  and  nonsegmented  code,  “include” 
files,  nested  conditional  assembly,  eight 
macro  directives,  and  external  CALR 
references.  The  ZLK  Task  Builder  com¬ 
bines  and  renames  program  and  data 
sections,  accepts  commands  from  console 
or  command  file,  builds  overlay  pro¬ 
grams,  and  can  convert  any  or  all  program 
sections  into  absolute  form.  The  ZLD  ob¬ 
ject  code  manipulation  utilities  down¬ 
load,  translate  to  Intel  hex  format,  and 
memory  load  into  dual-processor  config¬ 
urations.  The  ZEX  run-time  monitor, 
supplied  in  source  and  object  form,  sup¬ 
ports  any  dual  processor  system  that  has 
CP/M-80.  $395  gets  you  an  8-inch 
CP/M-80  formatted,  single-density  flop¬ 


py  that  also  runs  on  Cromemco’s  CDOS. 
Reader  Service  No.  237. 

You  can  get  Nevada  COBOL,  FOR¬ 
TRAN,  PILOT,  or  EDIT  from  Ellis  Com¬ 
puting  for  $29.95  each,  “the  same  pro¬ 
fessional  packages,”  they  tell  us,  “that 
have  sold  for  as  much  as  $300  per  copy.” 
Reader  Service  No.  239. 

Other  Stuff 

Could  you  use  Radio  Shack’s  help  in 
selling  your  software  to  the  TRS-80  com¬ 
puter  market?  The  Outside  Software  Sup¬ 
port  Program  is  available  to  professional 
software  developers,  even  those  design¬ 
ing  programs  not  intended  for  ultimate 
sale  through  Radio  Shack  outlets.  The 
Technical  Assistance  Program  provides  in¬ 
formation,  licenses  TRSDOS  and  TRS-80 
BASIC,  and  sells  TRSDOS  source  code 
and  bulk  run-time  packages.  The  Soft¬ 
ware  Review  Program  evaluates  third- 
party  software  and  makes  available  a  list¬ 
ing  of  reviewed  software  at  Radio  Shack 
Computer  Centers.  Submitted  software 
can  also  be  considered  for  Radio  Shack 
product  lines.  Reader  Service  No.  241. 

You  all  want  to  “plan,  build,  debug, 
and  program  a  working  computer  sys¬ 
tem!”,  don’t  you?  (That’s  not  my  excla¬ 
mation  point!)  You  need  Tab  Books’ 
The  Microcomputer  Builder’s  Bible  by 
Chris  Johnston.  The  book  discusses  all 
popular  8-  and  16-bit  chips,  focusing  on 
the  8080/Z80  processors,  describes  the  S- 
100/IEEE-696  bus,  and  provides  much 
software  information,  such  as  monitors 
and  operating  systems  (CP/M  in  particu¬ 
lar),  languages,  and  graphics  interfaces. 
Detailed  illustrations  and  schematics  de¬ 
scribe  building  a  computer  on  both  board 
and  system  levels,  along  with  advice  on 
soldering,  wire  wrapping,  constructing 
PC  boards,  and  debugging.  This  320- 
page  book  with  275  illustrations  costs 
$  1 8.95  in  hardback  and  $1 2.95  in  paper. 

Tab  Books  also  offers  From  BASIC 
to  Pascal  by  Ronald  Anderson,  buiding 
on  your  knowledge  of  BASIC  to  learn 
Pascal.  322  pages,  38  illustrations,  and 
$1  7.95/$  10.95.  Reader  Service  No.  243. 

You’ll  also  need  complete  informa¬ 
tion  about  all  currently  available  micro¬ 
processors,  so  get  the  Microprocessor 
Data  Book  by  S.  A.  Money  from  McGraw- 
Hill.  All  4-,  8-,  and  16-bit  microproces¬ 
sors  from  American,  European,  and 
Japanese  manufacturers  are  covered, 
with  illustrations  and  pinouts,  descrip¬ 
tions  of  architecture,  operating  parame¬ 
ters,  data  about  development  aids  and 


software,  specifications,  related  chips  by 
the  same  manufacturer,  and  a  cross- 
reference  of  equivalent  microprocessors. 
This  264-page,  8*/2-by-ll  book  costs 
$38.  Reader  Service  No.  245. 

Computer  leasing  seems  to  be  a  bur¬ 
geoning  trend  in  the  computer  business. 
North  Star  Computers  now  offers, 
through  U.S.  Leasing,  three-  to  five-year 
leases  on  the  Advantage,  with  system  up¬ 
grades  permitted.  Reader  Service  No.  247. 

Another  trend  appeared  in  the  press 
notice  from  Information  Unlimited  Soft¬ 
ware  announcing  that  Sears  has  joined 
their  product  distribution  network.  1US 
features  “professional”  software,  such  as 
EasyWriter  II  and  the  rest  of  the  Easy- 
Family  and  various  financial  packages.  In 
addition  to  Sears  Business  Systems  Cen¬ 
ters,  you  can  get  IUS  products  in  Com¬ 
puterLand  stores  and  all  authorized  IBM 
PC  dealers.  Reader  Service  No.  249. 

Another  recent  trend  is  the  require¬ 
ment  at  various  universities  for  all  new 
students  to  provide  their  own  computers. 
West  Philadelphia’s  Drexel  University  was 
the  first  to  announce  that  next  fall’s 
freshman  class  must  all  buy  computers 
for  classroom  work.  Drexel  will  probably 
require  a  computer  costing  about  $1000. 
Carnegie-Mellon  University  of  Pittsburgh, 
renowned  for  computer  and  robotics 
studies,  recently  announced  that  all 
entering  freshmen  in  1985  would  have  to 
supply  their  own  computers.  Clarkson 
College,  of  Potsdam,  NY,  will  provide 
personal  computers  for  all  freshmen  in 
fall,  1983.  They  have  arranged  to  pur¬ 
chase  over  1000  dual-processor  ZlOOs 
a  year  from  Zenith  Data  Systems  for  the 
next  four  years.  Students  will  pay  a  one¬ 
time  $200  maintenance  deposit  plus  $200 
per  semester  for  use  of  their  computers. 
Upon  graduation,  students  will  own  their 
computers,  although  those  who  don’t 
want  them  will  get  back  the  $200  depos¬ 
it.  The  computers  will  be  linked  in  a 
campus-wide  network,  and  have  CP/M- 
85,  ZDOS,  Z-BASIC  with  graphics,  For¬ 
tran,  COBOL,  and  Multiplan. 

1  probably  won’t  be  the  first  to  tell 
you  that  the  8th  West  Coast  Computer 
Faire  will  take  place  in  the  San  Francisco 
Civic  Auditorium  and  Brooks  Hall  com¬ 
plex  March  18  to  20,  1983,  but  1  can  turn 
you  on  to  a  free  subscription  to  the 
Silicon  Gulch  Gazette.  Reader  Service 
No.  251. 

TUG  Plug 

We  at  Dr.  Dobb’s  are  pleased  to  an- 
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nounce  the  arrival  of  a  new  kid  on  the 
block,  a  magazine  called  The  User’s  Guide, 
or  TUG  for  short.  This  periodical  has  just 
been  launched.  The  premiere  issue  looks 
great.  The  User’s  Guide  is  managed  and 
edited  by  Tony  Bove,  who  wrote  the 
Sybex  CP/M  book,  now  known  world¬ 
wide,  and  Cheryl  Rhodes,  a  computer 
literacy  instructor  and  programmer.  TUG 
emphasizes  classical  and  innovative  art 
covers  and  tongue-in-cheek  humor  in  the 
process  of  presenting  tutorial  material  of 
interest  to  a  wide  spectrum  of  readers. 
TUG  is  not  dedicated  exclusively  to 
tutorials  but  Tony  and  Cheryl  and  their 
staff  see  tutorials  as  an  area  of  great 
importance  especially  since  so  many 
companies  release  their  products  with 
documentation  lacking  in  true  human  fac¬ 
tors  engineering.  A  subscription  can  be 
obtained  by  enquiry  to:  The  User’s 
Guide,  117  Ware  Road,  Woodside,  CA 
94062. 

FOG  Bound 

F.O.G.,  The  First  Osborne  Group, 
formerly  F.O.U.G.,  the  First  Osborne 
Users  Group,  meets  on  the  third  Thurs¬ 
day  of  every  month  at  the  Dysan  Audi¬ 
torium,  Patrick  Henry  Drive,  Santa  Clara, 
California.  If  you  use  an  Osborne,  you 
will  be  pleased  to  make  the  acquaintance 
of  these  nice  people.  The  club  name  was 
modified  due  to  frequent  mispronuncia¬ 
tion  of  the  acronym  by  various  partici¬ 
pants  especially  in  heated  discourse. 
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High  Praise  for  Small  C 

To  the  Readers  of  Dr.  Dobb’s: 

The  December  issue  of  Dr.  Dobb’s 
containing  the  first  installment  of  ver¬ 
sion  2  of  the  Small -C  compiler  was  defi¬ 
nitely  a  welcome  sight.  With  all  the  bug 
corrections  and  improvements  for  version 
1.0  which  have  been  dribbling  in  these 
last  couple  years,  it  was  becoming  clear 
that  someone  would  just  have  to  sit  down 
and  pull  together  all  the  pieces. 

Marlin  Ouverson  approached  me  with 
the  idea  of  an  official  rewrite  of  the  little 
compiler.  Though  I  was  eager  to  give  it  a 
shot,  there  was  just  no  way  to  find  all  the 
spare  time  required  to  do  it  right.  At  the 
same  time,  it  was  clear  (at  least  to  me) 
that  there  were  some  pretty  respectable 
Small-C  experts  emerging  from  the 
readership  of  Dr.  Dobb’s  who  were  quite 
possibly  more  familiar  with  the  original 
compiler  than  I  (odd  thought,  that). 

So  Marlin  and  I  pondered  the  pro¬ 
blem  and  soon  realized  there  was  one 
name  which  had  appeared  more  than  once 
in  regards  to  Small-C  .  .  .  J.E.  Hendrix. 
But  could  we  ask  him  to  do  it?  Marlin 
contacted  him  and,  well,  you  can  see  the 
results. 

I  want  to  make  it  quite  clear  that  my 
only  role  in  this  was  sending  to  Jim  a  rath¬ 
er  open-ended  wish  list.  From  my  sug¬ 
gestions  (most  of  which  he  had  already 
anticipated  or  even  implemented),  and 
from  those  of  Neal  Block  and  Dr.  James 
Van  Zandt,  Jim  somehow  found  the  time 


necessary  to  fix  the  old  bugs,  check  off 
our  improvement  wish  lists,  and  toss  in 
some  compile-time  options  of  his  own.  I 
consider  the  finished  product  an  excellent 
product. 

Some  readers  may  wish  for  features 
not  yet  implemented  (naturally,  any  pro¬ 
grammer  wants  all  the  language  features 
possible).  Jim  is  as  aware  of  those  as  any¬ 
one.  However,  my  own  feeling  is  that  he 
chose  exactly  the  right  place  to  stop  de¬ 
velopment,  chase  out  the  bugs,  and  get 
the  thing  into  print.  It  is  the  same  deci¬ 
sion  I  made  many  months  (and  features) 
ago. 

I  have  no  doubt  that  this  new  version 
represents  far  more  work  than  the  origi¬ 
nal  (which  was  less  than  a  month  of  spare 
time  in  the  cooking).  And  because  of 
that,  it  is  a  much  more  generous  gift. 
Sincerely, 

Ron  Cain 

200  Meadow  Drive 
Boulder  Creek,  CA  95006 

Dear  DDJ, 

Congratulations!  A  first  class  effort! 
The  December  issue  was  worth  my  whole 
year’s  subscription.  I  was  very  impressed 
with  Mr.  Hendrix’s  method  for  evaluating 
constant  expressions,  and  for  dumping 
redundant  code.  His  evaluation  of  the 
“switch/case/default”  is  much  more  ele¬ 
gant  than  the  method  I  had  devised  for 
my  own  extensions.  The  whole  article  is 
an  object  lesson  in  the  value  of  public- 


domain  software,  and  how  it  may  evolve 
into  ever  more  useful  programs. 

There  is,  however,  a  minor  bug  in 
the  implementation  of  the  “switch/case/ 
default”  triad.  A  construct  such  as 

while  (  *x  ) 

switch  (  *x++  ) 

■i 

case  A:  continue; 

case  B: . ; 

V 

will  result  in  a  jump  to  an  undefined  label, 
when  the  code  for  the  “continue”  state¬ 
ment  is  generated.  What  should  happen  is 
a  branch  to  the  loopback  point  of  the  en¬ 
closing  “while”  statement,  (cf.  Kernighan, 
B.W.  and  Ritchie,  D.M.,  The  C  Program¬ 
ming  Language ,  Appendix  Z,  section  9.9, 
Prentice  Hall  Software  Series,  ISBN 
0-13-110163-3). 

The  fix  involves  minor  changes  to 
the  calls  to  “addwhile”  in  “dowhile,”  and 
“docont,”  and  a  new  function,  “backq” 
(see  Listing,  page  XX).  This  fix  has  the 
side-effect  that  a  “continue”  inside  a 
“switch”  which  has  no  enclosing  loop 
will  generate  the  code  for  a  “break,” 
although  the  “no  open  loops”  error  will 
be  generated. 

I  hope  that  this  is  of  some  interest. 
Yours  faithfully, 

Andrew  Macpherson 
29  Tisbury  Road,  Apt.  7 
HOVE 

E.  Sussex,  BN3  3BJ. 

England 


EDITORIAL 


As  the  1983  issues  of  Dr.  Dobb’s  Journal  unfold,  you 
may  see  a  few  slight  cosmetic  or  content  changes.  One  thing 
that  you  will  notice  as  time  goes  on  is  that  the  listings  we 
will  be  giving  you  will  be  shorter  and  meatier.  The  central 
ideas  behind  many  listings  may  be  condensed  into  exem¬ 
plary  pieces  of  code  which  may  be  more  instructive.  In  ad¬ 
dition,  we  hope  to  present  more  flowcharts  and  algorithms 
so  that  the  ideas  presented  may  be  generalized  more  easily. 
When  we  do  a  condensation,  we  will  also  endeavor  to  make 
the  complete  listing  available  to  those  who  wish  a  copy.  We, 
of  course,  are  still  open  to  publishing  longer  listings  if  the 
listings  are  of  sufficient  import  or  if  we  deem  it  necessary 
in  the  interest  of  clarity.  This  is  an  attempt  to  get  more 
editorial  material  to  you,  the  readers,  and  we  would  love 
feedback  on  how  well  it  serves  your  needs. 

Another  way  in  which  we  hope  to  serve  you  in  the 
coming  year  is  by  continuing  to  publish  top  quality  adver¬ 


tisements.  We  pride  ourselves  on  the  integrity  of  our 
advertisers,  as  well  as  our  editorial-to-advertising  ratio.  In 
those  very  rare  instances  when  an  advertiser  is  providing 
poor  services  (or  more  importantly  no  service),  we  would 
like  to  hear  from  you  as  quickly  as  possible  in  order  to 
investigate  and  take  appropriate  steps.  Lately  we  have 
received  some  complaints  (and  registered  some  of  our  own) 
about  a  couple  of  our  past  advertisers.  We  regret  this 
inconvenience  to  our  readers,  but  it  is  impossible  to  screen 
out  on  the  front  end.  While  caveat  emptor  is  still  the  rule  of 
the  marketplace,  it  helps  to  know  where  you  can  go  for 
reputable  purveyors  of  products  and  services.  With  your 
assistance,  Dr.  Dobb’s  will  remain  such  a  place. 

Keep  us  posted! 

Reynold  Wiggins 
Associate  Editor 
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MODIFICATIONS  TO  SMALL  C  COMPILER  FOR  CORRECT  'CONTINUED 


/* 
*  * 


4  I  n  t  k  ; 


1  e  n  e 

w  n  e  s  t  1  n 

9 

level 

C  ptr 

,  s  w  i  t  f  1 

a  9 

) 

1  ,  s  w 

i  t  f  lag; 

ptr  I 

WQSP  1 

= 

c  s  p  ; 

ptr  I 

WQEXIT 

1 

=  g  e  t  1  a  b  e  1 

(  >  ; 

i  f  ( 

s  w  1  t  f  1  a  g 

= 

=  YES  ) 

4  i 

n  t 

*  P  ; 

1  f 

C 

p  =  backq 

(  )  ) 

ptr  I 

WQLOOP  J 

=  P  1 

e  1  s 

e 

ptr  I 

WQLOOP  ] 

=  ptr 

V 

else 

ptr 

l 

WQLOOP  1 

=  g  e  t  1  a  b  e  1 

I  (  >  ; 

i  f  C 

wqptr  =  = 

WQMAX  ) 

4 

err 

o  r 

(  "too  many  active 

while 

e  x  1 

t 

(  ERRCODE 

)  ; 

WQLOOP  ] ; 


k  3  0  ; 
while 


(  k  <  W  QS  I  Z  ) 

*wqptr++  =  ptr  I  k++  1; 


b 

/* 

*  *  docont  jump  to  loopback  point  of  Innermost  loop 

*  / 

docont  (  ) 

4  int  *ptr  ; 

if  (  !  (  ptr  3  backq  ())) 

4 

error  (  "no  open  loops"  ); 

if  (  !  (  ptr  *  readwhile  ()))  return; 


modstk  (  ptr  I  WQSP  J  ); 
jump  (  ptr  [  WQLOOP  I  ); 


backq  new  function  :  find  the  innermost  loop  on  while  queue 


backq  (  ) 

4  int  ‘inner,  “outer; 

if  (  wqptr  ==  wq  )  return  0; 
inner  3  wqptr  -  WQSIZ; 
outer  *  inner  -  WQSIZ; 
while  ((  outer  >  3  wq)  &  & 

(  outer  [  WQLOOP  1  ==  inner  [  WQLOOP  1  )) 

4 

inner  =  outer; 
outer  - =  WQSIZ; 

> 

If  (  inner  I  WQLOOP  1  ==  inner  I  WQEXIT  I)  inner  =  0; 

return  inner; 


No  BDOS  Trace 

Dear  Doctor, 

I  have  never  been  able  to  afford  a 
subscription  but  do  enjoy  DDJ  when  I 
can  borrow  it  from  my  friends.  In  the  last 
issue  so  acquired  (December,  1982)  there 
was  a  letter  from  a  person  having  trouble 
using  a  debugger  to  trace  execution  of  a 
program  through  the  CP/M  BDOS. 

This  will  never  work  no  matter  how 
clever  one  is  with  the  break  points  be¬ 
cause  the  CP/M  BDOS  is  not  re-entrant. 
On  entry  to  the  BDOS  at  0005h,  you 
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jump  to  code  which  saves  register  argu¬ 
ments,  the  stack  pointer,  and  the  return 
address  at  fixed  locations.  The  BDOS 
then  switches  to  an  internal  stack  for  fur¬ 
ther  operations. 

Since  DDT/SID/ ZID  use  BDOS  char¬ 
acter  I/O  when  displaying  the  trace  infor¬ 
mation,  attempts  to  trace  through  the 
BDOS  will  result  in  the  saved  values  being 
overwritten  and  destroyed  by  the  recur¬ 
sive  BDOS  call  made  by  the  debugger. 

(Letters  continued  on  page  74) 


PISTOL 

A  Forth-like  Portably  Implemented 
STack  Oriented  Language 


The  development  of  PISTOL  is  based  on  STOIC,  STack 
Oriented  Incremental  Compiler,  a  compiler  developed  by  the 
Harvard  and  MIT  Bio -Engineering  center  in  1977.  STOIC  is 
available  from  the  CP/M  Users  Group  as  Volume  23a.  Forth  is 
available  from  the  Forth  Users  Group  (FIG),  Box  1105,  San 
Carlos,  CA  94070.  PISTOL  is  being  provided  in  the  public 
domain  with  this  article.  It  may  be  reproduced  and  distributed 
for  any  and  all  uses  so  long  as  a  proper  copyright  notice  and 
acknowledgement  of  source  is  included. 

PISTOL  is  available  on  Disk  (see  Figure  I,  page  14)  for 
$10.00  plus  the  price  of  the  media,  through  the  BDS-C  User’s 
Group,  Box  287,  Yates  Center,  KS  66783,  and  through  the 
Amateur  Computer  Group  of  New  Jersey  (ACGNJ),  Box  319, 
South  Bound  Brook,  NJ  08880.  -  Ed. 


PISTOL  was  developed  with  a  different  philosophy,  per¬ 
haps,  than  its  predecessors.  Forth  and  STOIC.  It  is  my 
belief  that  Forth -like  languages  should  be  available  to 
users  of  large  mainframe  machines  as  well  as  mini  and  micro 
users.  I  have  concentrated  upon  the  following  goals:  user 
friendliness,  portability  between  machines  with  different 
word -lengths  and  machine  instruction  sets,  KISS  (“Keep  it 
simple  stupid”),  and  freedom  from  many  of  the  idiosyncrasies 
that  have  irritated  me  with  Forth  and,  to  a  lesser  degree,  STOIC. 
Lastly,  I  wanted  PISTOL  to  be  as  self-contained  and  complete 
as  possible.  Obviously,  the  result  is  not  as  chintzy  about  RAM 
and  file  space  as  its  predecessors. 

Before  the  Forth  enthusiast  is  discouraged  from  examining 
this  language  further,  I  hasten  to  add  that  there  are  a  number 
of  simplifications  that  I  have  introduced  which  m'ight  be  worth 
considering.  I  shall  now  detail  some  of  the  ways  that  PISTOL 
differs  from  classic  Forth. 

Following  the  lead  of  STOIC,  PISTOL  supports  strings  as 
a  fundamental  element  of  the  language.  They  are  manipulated 
with  almost  the  same  manner  and  ease  as  numbers.  For  exam¬ 
ple,  to  define  a  word,  “DEMO,”  Forth  starts  off  with: 

:  DEMO .  .  . 

whereas  STOIC  and  PISTOL  start  off  with: 

‘DEMO  :  .  .  . 

This  could  be  very  important  if  the  choice  of  name  is  to  be 
flexible.  How  would  one  write  in  Forth  the  definition  for  “3” 
depending  upon  whether  the  constant  “FRENCH”  were  true 
or  not? 

FRENCH  IF 
‘TROIS 
ELSE 


by  Ernest  E.  Bergmann 


Ernest  E.  Bergmann,  Physics,  Bldg.  No.  16,  Lehigh  University, 
Bethlehem,  PA  18015. 


‘THREE 
THEN  :  3  ; 

Again,  following  the  lead  of  STOIC,  we  compile  everything 
into  a  compile  buffer.  Thus  there  is  no  interpret  mode  as  in 
Forth.  This  change  simplifies  the  language  because  we  don’t 
have  to  code  two  distinct  modes  and  provide  two  separate  sets 
of  rules.  To  illustrate  this  point: 

20  0  DO  (whatever)  LOOP 

would  work  just  fine  typed  in  for  immediate  execution;  it  does 
not  have  to  be  embedded  in  a  definition! 

We  differ  from  STOIC  and  early  forms  of  Forth  by 
storing  the  complete  name  of  each  definition.  STOIC,  for  ex¬ 
ample,  saves  only  the  first  five  letters  (and  a  letter  count). 
This  was  done  because  it  simplifies  coding  the  language  origi¬ 
nally,  the  variable  length  of  the  name  might  actually  take  no 
more  space,  and,  most  importantly,  when  we  use  the  disassem¬ 
bler  and  the  trace  features  of  PISTOL,  we  see  the  full,  original 
names  of  the  words  used. 

We  have  “packaged”  PISTOL  so  that  the  disassembler, 
trace,  and  editor  are  always  resident.  (They  probably  could  be 
removed,  but  why  not  enjoy  the  synergism  of  the  complete 
environment  at  your  fingertips!) 

The  prompt  is  much  more  informative  than  in  other  lan¬ 
guages.  STOIC  started  this  trend  by  displaying  “nesting  depth.” 
We  have  continued  this  trend  by  displaying  the  number  of 
elements  on  the  parameter  stack  when  it  is  not  empty.  The 
prompt  explicitly  shows  the  current  number  base  being  used. 
If  the  nesting  depth  is  not  zero,  one  sees  what  one  is  “nested 
into.”  This  information  is  used  also  for  more  vigilant  syntax 
checking.  I  have  worked  with  the  earlier  languages  that  fatally 
“bomb”  with  such  lines  as: 

IF. 

or 

DO . . THEN 


We  have  been  able  to  remove  the  “arbitrary”  restriction 
that  a  “ :  .  .  .  definition  can  only  be  made  at  level  0.  We  can 
and  do  make  extensive  use  of  definitions  that  are  nested  inside 
of  conditional  expressions  or,  even,  inside  of  other  definitions! 

We  do  not  support  “CODE”  definitions.  This  is  because 
we  wish  to  guarantee  portability  of  source  code  between  widely 
differing  machines.  In  addition,  we  wish  to  maintain  our  goal 
of  user  friendliness  by  being  able  to  disassemble  virtually  every¬ 
thing.  Obviously  we  depart  from  STOIC  particularly  on  this 
point,  but  STOIC  is  not  portable  to  non-8080-compatible 
machines. 

Because  the  primitives  of  PISTOL  are  defined  in  some 
high-level  language,  such  as  Pascal  or  C,  it  is  expected  that 
additional  primitives  might  be  added  to  the  “kernel”  as  the 
need  arose.  For  example,  in  order  to  increase  the  speed  of 
PISTOL  for  block  move  operations  in  editing,  we  might  want 
to  replace  LDDR,  a  slow,  PISTOL  language  definition.  On  a 
Z80  machine  there  is  an  obvious  machine  hardware  instruction 
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Figure  1. 

Contents  of  PISTOL  Diskette 


CABORT.  ASM 

CABORT.CRL 

COREl. 

ENVIRON.  DOC 
PBASE. 

PISTB.C 

PISTB.CRL 

PISTC.C 

PISTC.CRL 

PISTD.C 

PISTD.CRL 

PISTE. C 

PISTE. CRL 

PISTF.C 

PISTF.CRL 

PISTGEN.SUB 

PISTOL  .C 

PISTOL.COM 

PISTOL. CRL 
PISTOL.  DOC . 
PISTOL.  H 
PISTOL.  PAS 

PISTSUB.SUB 
READ. ME 
SESSIONO.DOC 
SESSION  1 .  DOC 


code  for  MAC  to  make  CABORT.CRL  that  contains  the  abort()  function,  similar  to  the  setjmpO  and 
longjmpO  of  BDS  C  v  1.45a 

“core  image”  that  results  from  compiling  PBASE  (see  PISTOL.DOC  for  details) 
suggests  at  least  48  K  RAM  total 

PISTOL  source  code  used  to  “educate”  PISTOL.COM  to  be  as  smart  as  described  in  PISTOL.DOC 
module  #2 

module  #3 

module  #4 

module  #5 

module  #6 

SUBMIT  file  to  generate  this  disk 
main  module 

***  this  and:  ’COREl  RESTORE  will  give  you  a  new  development  language;  try  it,  you’ll  like  it  (check 
the  40K  documentation  for  best  results!) 

40K  documentation  of  PISTOL 
constants  and  externals  for  PISTOL 

42K  Pascal  version  of  PISTOL  that  runs  on  a  DEC- 20  mainframe  computer;  it  helps  define  the  way 

PISTOL  should  be  created 

SUBMIT  file  to  compile  and  link  all  C  modules 

History  and  editorial  vis-a-vis  with  Forth  and  STOIC 

example,  chatty  session  showing  some  of  the  most  basic  operations  available  in  PISTOL 
more  of  the  above,  shows  how  CONSTANTS,  VARIABLES,  new  words  and  macros  are  created 


that  could  be  used  instead.  One  could  add  this  word  to  the 
kernel  and  “generalize”  PBASE  by  replacing: 

‘LDDR  :  . .  . 
by 

‘LDDR  DUP  FIND  IF 

DROP 

ELSE 

THEN 


To  slightly  ameliorate  the  lack  of  “CODE”  definitions, 
we  have  provided  an  “inline  macro”  facility.  If  one  creates  a 
word  definition  using: 

$:...;$ 

instead  of: 

then  when  the  word  is  encoded,  the  contents  of  the  definition 
are  compiled  into  the  compile  buffer  instead  of  a  “call”  to  the 
definition. 

A  number  of  conveniences  are  provided  which  are  not 
common  to  the  “competition.”  The  crude  line  editor  that  is 
provided  with  PISTOL  can  be  used  in  a  BASIC-like  fashion.  In 
addition  to  being  able  to  LOAD  files,  one  can  LOAD  the  edit 
buffer  as  well,  starting  at  any  particular  line  number.  For 
example: 


‘MYWORK.PIS  LOAD 

and 

3  LOAD 

There  are  times  when  it  is  nice  to  record  the  terminal  ses¬ 
sion.  Instead  of  using  a  printer,  one  can  create  a  disk  file  that 
will  hold  the  record: 

‘XYZ  LISTFILE 
LIST  ON 

(this  will  be  recorded) 

LIST  OFF 

(this  will  not) 

LIST  ON 

(this  will) 

etc. 


BYE  (this  way  of  exiting  PISTOL  will  properly  close 
all  files  that  are  opened  for  writing) 

Undoubtedly,  there  are  other  important  differences  that 
I  have  not  discussed;  I  hope  that  you  will  give  PISTOL  a  try.  I 
would  be  most  pleased  to  receive  your  comments,  construc¬ 
tive  criticisms  and  questions. 
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DOBB’S  EX  MACHINA 


by  Hank  Harrison 


Anadex  Has  Competition! 

At  last  Anadex,  one  of  the  most  pop¬ 
ular  American-made  dot  matrix  printer 
manufacturers,  will  probably  have  to 
bring  their  replacement  ribbon  prices 
down.  Now  Aspen  Ribbons,  Inc.  of  Boul¬ 
der,  Colorado,  cuts  that  price  by  at  least 
50%  at  the  retail  level  in  quantities  of 
one.  For  larger  orders,  the  price  goes 
down  even  further.  The  Aspen  ribbons 
are  manufactured  in  America,  and  no  part 
of  the  ribbon  is  imported.  Our  testing  of 
the  two  ribbons  side  by  side  found  no 
significant  difference,  and  the  Aspen  is 
slightly  better  in  mechanical  operations, 
bearing  surface,  etc.  As  with  Anadex,  one 
size  fits  the  Plessy  PM-LC11  and  the  en¬ 
tire  Anadex  range,  9000,  0991,  9500, 
9501,  9620,  9625,  and  all  DP  series,  the 
WP6000  and  others.  One  Aspen-Anadex 
replacement,  in  quantities  between  1  and 
35  will  cost  $13.00  per  unit,  144-287 
units  (wholesale)  will  cost  $8.75  per  unit, 
and  any  order  above  864  units  will  be 
considered  O.E.M.  and  will  go  out  at 
$6.75  per  unit.  Color  choices  are  available 
at  slightly  higher  prices. 

For  further  information,  contact: 
Aspen  Ribbons,  Inc.,  1700  N.  55th  St., 
Boulder,  Colorado  80301.  Telephone 
(303)  444-4054,  or  toll  free  (800) 
525-0646. 

An  Apple  a  Year  .  .  . 

All  one  has  to  do  to  cause  Appleplexy 
at  Apple  these  days  is  mention  the  word 
lie.  This  is  the  code  word  for  the  latest 
Apple  Surprise  due  any  year  now.  By 
skillful  use  of  VLSI  technology,  Apple 
has  been  able  to  design  a  machine  that 
will  please  everyone  interested  in  Apples 
as  it  looks  externally  like  the  old  Apple. 

Everyone  knows  that  Apple  is  work¬ 
ing  feverishly  on  the  LISA  project,  a 
16-  to  3 2 -bit  system  that  will  display  cer¬ 
tain  levels  of  artificial  intelligence.  The 
“Lisa”  is  the  UNIX  Mother  Project  that 
will  hook  up  with  the  MACKINTOSH 
68000  machine.  Lisa  and  Mackintosh  will 
not  talk  to  Super  lie  and  III,  but  who 
cares?  It  is  rumoured  that  Mackintosh  will 
be  portable,  or  at  least  portabalizabie. 

The  Super  He  will  be  a  boon  and  a 
Godsend  and  it  will  keep  Apple  fans  in 
the  fold.  It  will  also  contain  a  number  of 
bells  and  whistles  that  perhaps  should 
have  been  available  in  the  past  but  which 
for  various  reasons  were  deemed  unapple- 
ish.  It  now  has  upper  and  lower  case, 
cursor  controls  in  all  directions,  and  64K 
RAM  standard  with  expandable  memory 


architecture.  The  new  system  will  have 
the  80  column  capability,  a  paddle  0  and 
paddle  1  port  enhancement,  monitor 
support  for  HIRES  graphics,  auxilliary 
video  with  row  addressing,  a  better  and 
easier-to-use  back  panel  with  external 
connectors,  a  delete  key,  soft  keys,  relo¬ 
catable  French  and  German  key  caps  and 
special  International  Key  Board  ROMs. 

Full  file  compatability  between  Ap¬ 
ple  II  and  Apple  III  is  assured  and  a  true 
applications  environment  will  be  striven 
for  through  Profile,  Duofile  and  Unifile, 
hard  disk  protocols.  The  floppies  will 
have  more  capacity,  possibly  even  a  half¬ 
height  profile,  and  the  Z-80  card  will 
continue  as  a  co-processing  option  for 
CP/M  devotees. 

As  to  software,  it  appears  that  DOS 
3.3  will  be  frozen  but  will  continue  up 
the  scale  with  PRODOS  which  will  be 
available  in  Spring,  1983. 

Other  features  that  are  rumored  to 
be  included  in  the  new  Super  Apple  are 
Autostart  ROM,  Diagnostics,  baud  rate 
switching  support  and  lots  of  software. 
We  think  the  price  should  stay  in  the 
$2000  dollar  range  and  we  don’t  think 
Apple  will  get  caught  in  a  price  war.  Hats 
off  to  Apple  on  this  one.  , 

Tiny  Scale  Apple  Polisher 

Tom  Crosley,  the  formidable  multi¬ 
lingual  consultant  who  developed  the 
hugely  successful  PIE  Writer  way  back 
when  the  40-column  board  was  the  stan¬ 
dard,  is  working  on  a  new  language  so 
simple,  it’s  elusive.  It’s  one  of  those 
“wish  I  had  thought  of  it”  languages,  the 
name  of  which  I  cannot  divulge.  It  is, 
however,  a  small  whopper- derived  from 
PL/M,  Pascal,  and  C,  a  portable  language 
intended  for  both  systems  and  applica¬ 
tions  programming  on  micros.  The  new 
language  is  tiny  and  is  more  effective  as  a 
whole  than  any  of  its  component  lan¬ 
guages.  We  hope  to  feature  it  in  Dr.  Dobb 's 
in  its  pre-release  phase. 

A  Whale  of  an  Assembler 

David  Eyes,  head  of  technical  product 
development  at  Hayden’s  new  software 
think-tank  in  Lowell,  Massachusetts,  is  ru¬ 
mored  to  be  working  on  an  amazing  macro 
assembler  package  authored  by  a  very  tal¬ 
ented  new  face  from  New  Mexico.  The 
new  “low  ticket”  package  will  go  on  the 
block  sometime  in  early  1983.  It  is  dedi¬ 
cated  to  6502  assembly  language  but  the 
low  ticket  analogy  ends  there.  The  new 


package  features  forty  monitor  com¬ 
mands,  more  than  fifty  editor  commands, 
a  macro  library,  a  subroutine  library  and 
a  fully  integrated  architecture.  The  pro¬ 
gram  utilities  effectively  utilize  memory 
in  a  clever  and  never-before-used  fashion 
so  that  the  entire  package  can  be  thought 
of  as  a  workbench  system  with  tools.  This 
macro  assembler  can,  in  edit  mode,  access 
a  string  buffer,  a  character  buffer,  and  an 
on-screen  text  buffer.  It  comes  with  an 
extensive  documentation  package.  The 
product  should  surface  for  air  soon  and 
Dr.  Dobb’s  will  be  reporting  on  it. 

Semi -Disk  Systems 

I  hate  semi-disk  systems!  I  hate  any¬ 
body  whose  hardware  works  the  first 
time.  I  hate  them  too,  because  they  beat 
me  to  a  logo  device  — the  universal  sign  of 
negation.  I  wanted  it  for  use  with  a  book 
cover,  the  title  of  which  was  Not  Dead, 
but  they  can  have  it  because  their  board 
works  better  than  my  book. 

Anyway,  the  500K  semi-disk,  in  the 
S-100  form,  is  the  neatest  board  job  I’ve 
ever  seen.  It  ran  a  1 15K  Wordstar  text  file 
using  control  QR  from  head  to  foot  in  12 
seconds  on  an  IBM  PC  at  Comdex.  Very 
impressive.  My  Victor  9000  does  the 
same  thing  in  a  minute-and-a-half,  given 
the  disk  access  using  the  8088  and  126K. 
The  semi-disk  makes  an  8-bit  act  like  a 
16-bit  machine. 

As  currently  supplied,  the  semi-disk 
provides  an  optional  battery  back-up 
which  can  protect  data  in  RAM  for  ten 
hours.  Semi-disk  is  available  for  TRS-80, 
S-100,  and  the  IBM  PC.  A  full  and  ex¬ 
haustive  hardware  review  and  shakedown 
will  be  presented  in  DDJ  soon. 

MCDISPLAY 

MCDISPLAY  is  an  interface  module 
for  high-level  languages  running  on  any 
Z-80,  8080  or  8085  system.  It  requires 
54K  of  memory  and  provides  a  very  sim¬ 
ple,  compact  and  elegant  way  of  interac¬ 
tive  communication.  Version  I  supports 
Microsoft  BASIC  (both  the  version  5.2 
interpreter  and  the  version  5.3  compiler). 
Modules  for  other  languages  will  follow. 

Programs  designed  with  the  MCDIS¬ 
PLAY  runtime  module  are  organized 
around  the  display.  This  method  provides 
the  programmer  with  the  capability  of 
complete  and  controllable  access  to  the 
user  without  having  to  write  large  a- 

(Continued  on  page  73) 
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16-BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


This  month  I  will  devote  the  column 
to  a  review  of  Concurrent  CP/M-86 
(CCPM),  which  has  recently  been  released 
by  Digital  Research  for  the  IBM  Personal 
Computer.  The  CP/M-86  operating  system 
was  customized  and  marketed  for  the  PC 
as  an  IBM  software  prodhct,  but  apparent¬ 
ly  Digital  Research  was  displeased  with 
the  result  and  undertook  to  implement 
and  sell  the  Concurrent  version  directly. 
This  is  fortunate  from  the  standpoint  of 
evaluating  the  operating  system’s  perfor¬ 
mance,  since  it  gives  us  an  “official”  ver¬ 
sion  which  has  been  presumably  optimized 
and  polished  to  the  complete  satisfaction 
of  its  inventors  —  we  don’t  need  to 
concern  ourselves  with  the  hardware- 
dependent  foibles  that  sometimes  creep 
into  OEM  implementations.  Versions  of 
Concurrent  CP/M-86  for  other  8086/88 
microcomputers  will  be  available  eventu¬ 
ally,  but  will  probably  be  many  months 
in  arriving. 


A  Little  Background  Information 

For  those  of  you  who  are  not  famil¬ 
iar  with  the  Digital  Research  family  of 
operating  systems,  a  brief  overview  may 
be  in  order.  The  original  CP/M,  now 
known  as  CP/M-80,  is  a  single  user  operat¬ 
ing  system  for  8080/Z-80  microcomput¬ 
ers  that  provides  hardware-independent 
console,  printer,  and  file  handling  services 
for  application  software  and  program  de¬ 
velopment  tools.  CP/M-80  has  become 
the  industry  standard  for  8 -bit  micro¬ 
computers.  There  are  several  hundreds  of 
thousands  of  licensed  installations,  and  an 
unknown  but  probably  also  enormous 
number  of  unlicensed  copies  in  circula¬ 
tion  (as  well  as  a  large  number  of  licensed 
users  of  “CP/M  compatible”  operating 
systems  such  as  CDOS,  SDOS,  and  Turbo- 
DOS).  The  third  major  revision  of  CP/M- 
80  has  just  been  released,  with  an  im¬ 
proved  file  manager,  enhanced  utilities, 
and  provision  for  powerful  graphics  ex¬ 
tensions. 

The  multi-user  version  of  CP/M-80  is 
known  as  MP/M-80,  and  is  now  in  its  sec¬ 
ond  major  release.  The  original  version 
of  MP/M  had  irksome  deficiencies  in  per¬ 
formance,  was  difficult  to  configure,  and 
included  no  provision  for  file  or  record 
locking  so  that  the  integrity  of  data  could 
be  protected  when  several  programs  were 
executing  simultaneously.  These  problems 
were  virtually  eliminated  in  MP/M-80 
version  II,  which  is  a  very  acceptable  real¬ 


time,  multi-tasking  operating  system; 
however,  it  is  inherently  limited  by  the 
speed  and  power  of  the  host  8 -bit  micro¬ 
processor  and  cannot  practically  support 
more  than  about  four  consoles  in  stan¬ 
dard  systems. 

CP/M-86  is  a  translated  version  of 
CP/M-80  for  the  Intel  8086/88  family  of 
microcomputers.  From  the  user’s  point  of 
view,  operation  of  CP/M-86  is  extremely 
similar  to  that  of  CP/M-80,  with  most  of 
the  same  commands.  Disk  allocation  and 


file  management  are  identical  to  that  of 
CP/M-80,  so  that  data  may  be  easily  trans¬ 
ported  between  programs  running  on  ei¬ 
ther  operating  system.  CP/M-86  has  been 
a  fairly  stable  operating  system  since  its 
release,  and  has  not  required  any  major 
revisions.  The  performance  of  CP/M-86 
has  been  limited  somewhat  by  the  con¬ 
straint  of  compatibility  with  the  8-bit 
systems,  and  it  has  run  into  stiff  competi¬ 
tion  for  the  hearts  of  microcomputer 
manufacturers  and  users  from  the  Micro- 
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Table  1. 

Concurrent  CP/M-86  commands  and  utilities. 

Command  name 

Action 

ABORT 

Stops  execution  of  a  task. 

ASM86 

8086/88  assembler. 

CONFIG 

Sets  operating  parameters  for  serial  ports. 

DDT86 

8086/88  interactive  debugger. 

DIR 

Display  disk  directory. 

DSKMAINT 

Initialize  or  copy  disks. 

DSKRESET 

Log  in  diskette. 

ED 

Line  editor. 

ERA 

Erase  file(s). 

ERAQ 

Erase  file(s)  with  query. 

FUNCTION 

Program  special  function  keys. 

GENCMD 

Create  executable  file  from  assembler 
output. 

HELP 

On-line  assistance  for  system  commands. 

PIP 

Transfer  and  manipulate  files  among 
other  things. 

PRINTER 

Select  or  display  attached  printer  number. 

REN 

Rename  file(s). 

SDIR 

Sorted  directory  listing  with  many 
options. 

SET 

Controls  password  protection  and  file 
attributes. 

SHOW 

Displays  disk  and  system  parameters. 

STAT 

Display  file  information,  assign  attributes. 

SUBMIT 

Batch  processing  utility. 

SYSDISK 

Designate  the  “system”  disk  drive. 

TOD 

Set  or  display  time  and  date. 

TYPE 

Display  contents  of  a  text  file. 

USER 

Select  or  display  the  current  user  number. 

VCMODE 

Set  mode  and  buffer  size  for  virtual 
consoles. 

soft  counterpart  “MS-DOS.” 

Finally,  MP/M-86  is  available  as  the 
upward -compatible,  multi-user  version  of 
CP/M -86.  This  is  an  exceedingly  power¬ 
ful  microcomputer  operating  system 
readily  capable  of  supporting  up  to  six¬ 
teen  users.  It  offers  many  additional  so¬ 
phisticated  services  to  the  programmer 
such  as  queue  management,  dynamic  mem¬ 
ory  allocation,  easy  installation  of  resi¬ 
dent  system  processes,  multiple  printer 
support,  and  task  spawning.  It  requires  a 
comparatively  large  amount  of  memory 
(256  Kbyte  RAM  systems  are  common) 
and  is  usually  hard-disk  based.  Efficient 
implementations  of  MP/M-86  with  prop¬ 
er  interrupt  handling  and  buffered  I/O 
are  quite  complex  and  require  several 
man-months  of  work.  For  this  reason,  it 
has  been  slow  to  appear  on  the  market 
for  the  various  8086/88  microcomputers. 
An  unusual  variant  called  MP/M  8-16  is 
sold  by  G&G  Engineering  for  the  Compu- 
Pro  8085/8088  dual  processor  board.  It 
allows  the  interleaved  execution  of  pro¬ 
grams  coded  for  the  8080  or  8086  on  the 
same  microcomputer  without  any  special 
intervention  by  the  user. 

What  is  Concurrent  CP/M -86? 

To  quote  Digital  Research,  “Con¬ 
current  CP/M-86  is  a  single-user,  multi¬ 
tasking  operating  system  that  lets  you  run 
multiple  programs  simultaneously  by  di¬ 
viding  tasks  between  virtual  consoles.”  In¬ 
spection  of  the  documentation,  services, 
and  utilities  of  CCPM  reveals  it  to  be  a 
slightly  stripped-down  version  of  MP/M- 
86,  with  some  rather  novel  modifications. 
From  the  operating  system’s  perspective, 
there  are  four  user  consoles  which  can 
originate  and  interact  with  executing  pro¬ 
cesses.  From  the  user’s  point  of  view, 
there  is  one  physical  console  which  serves 
as  a  “window”  and  can  be  switched  at 
will  between  any  of  four  virtual  consoles 
(see  Figure  1 ). 

The  terminal  handlers  for  the  four 
virtual  consoles  buffer  output  indepen¬ 
dently;  when  a  program  writes  to  a  virtual 
console  that  is  not  currently  being  viewed 
by  the  user,  the  characters  are  stored  into 
a  RAM  swapping  buffer  and  optionally 
spooled  into  a  disk  file  so  that  no  output 
is  lost.  When  that  virtual  console  is  finally 
selected  by  the  user,  the  saved  output  is 
recalled  from  the  swapping  buffer  and 
displayed  on  the  screen.  Toggling  the 
physical  console  between  the  four  virtual 
consoles  is  accomplished  merely  by  hold¬ 
ing  down  “Control”  and  keying  a  number 
between  0  and  3;  the  response  by  the 
operating  system  is  instantaneous.  While 
the  system  is  running,  the  status  line  at 
the  bottom  of  the  screen  displays  the  fol¬ 
lowing  information  for  the  currently  se¬ 
lected  virtual  console:  the  name  of  the  ac¬ 
tive  task,  the  unit  number  of  the  attached 
printer,  names  of  disk  drives  with  any 


open  files,  the  time,  and  the  status  of  cer¬ 
tain  keys  such  as  CAPS  LOCK  and  NUM 
LOCK. 

System  Requirements 

The  power  of  Concurrent  CP/M-86 
carries  a  hefty  price  tag  for  both  hardware 
and  software.  The  first  requirement,  of 
course,  is  that  you  fork  over  $350.00  to 
Digital  Research  for  a  single  user  license. 

Next  comes  the  hardware.  A  mini¬ 
mum  of  256  Kbytes  of  RAM  is  recom¬ 
mended  by  Digital  Research;  at  least  192 
Kbytes  must  be  present  in  order  to  boot 
up  the  system.  If  more  memory  is  avail¬ 
able,  part  of  it  can  be  allocated  as  a  “vir¬ 
tual  disk.” 

Two  disk  drives  are  mandatory ;  dou¬ 
ble-sided  drives  make  the  system  much 
more  pleasant  to  use  due  to  the  large 
amount  of  disk  storage  occupied  by  the 
various  system  utilities  and’  the  HELP 
text  file. 


Commands  and  Utilities 

Users  of  CP/M-80  and  CP/M-86  will 
find  much  that  is  familiar.  The  well-known 
commands  DIR,  ED,  ERA,  PIP,  REN, 
STAT,  SUBMIT,  TYPE,  and  USER  that 
hearken  back  to  the  early  days  on  the 
8080  operate  in  the  same  old  tried-and- 
true  manner. 

The  utilities  ABORT  (terminate  exe¬ 
cuting  task),  DSKRESET  (log  in  new 
diskette),  ERAQ  (selective  file  erase  with 
query),  PRINTER  (select  list  device), 
SDIR  (formatted  directory  with  file  sizes 
and  attributes  similar  to  STAT  *.*  or 
LST),  SHOW  (display  system  and  disk 
parameters),  SET  (control  disk  and  file 
attributes,  passwords,  and  timestamping), 
and  TOD  (set  or  display  system  time  and 
date)  work  in  the  same  manner  as  their 
counterparts  on  MP/M  systems. 

The  program  development  tools 
ASM86  (8086/88  assembler),  DDT86  (in¬ 
teractive  debugger),  and  GENCMD  (create 
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executable  command  file)  are  identical  to 
their  CP/M-86  counterparts. 

Finally,  there  are  a  number  of  utilities 
which  are  unique  to  the  IBM  Personal 
Computer  implementation  of  Concurrent 
CP/M-86.  CONFIG  allows  the  user  to 
control  the  baud  rate,  word  length,  parity, 
and  stop  bits  of  the  serial  ports.  DSK- 
MAINT  provides  formatting  and  copying 
of  single-  or  double-sided  diskettes. 
FUNCTION  allows  the  user  to  specify 
character  strings  for  each  of  the  pro¬ 
grammable  function  keys.  HELP  provides 
interactive,  on-line  explanations  and  ex¬ 
amples  for  any  of  the  system  commands. 
SYSDISK  allows  the  user  to  specify 
which  disk  drive  will  be  searched  for  a 
program  if  it  is  not  found  on  the  “cur¬ 
rent”  or  default  disk.  Finally,  VCMODE 
is  used  to  control  the  characteristics  of 
each  of  the  virtual  consoles.  See  Table  I 
on  page  21  for  a  more  condensed  list  of 
the  system  commands. 

File  Handling 

Concurrent  CP/M-86  incorporates  the 
Digital  Research  BDOS  (Basic  Disk  Oper¬ 


ating  System)  version  3,  which  is  also 
embedded  in  MP/M  version  II  and  sup¬ 
ports  many  advanced  file  management 
options.  This  BDOS  apparently  will  be¬ 
come  the  standard  for  all  of  the  DRI 
operating  systems  including  the  new 
CP/M-80  version  3.0. 

On  the  command  level,  diskettes  and 
individual  files  can  be  protected  by  pass¬ 
words.  Time  stamping  for  the  creation, 
update,  or  last  access  of  a  file  is  suppor¬ 
ted.  In  addition,  files  may  be  marked 
with  the  attributes  SYSTEM,  READ¬ 
ONLY,  and  ARCHIVED. 

On  the  programming  level,  executive 
service  calls  available  to  application  pro¬ 
grams  provide  full  support  for  file  and 
record  locking.  If  a  file  is  opened  in  “un¬ 
locked”  mode  by  a  program,  it  remains 
accessible  to  any  other  task  which  is  also 
willing  to  open  it  in  “unlocked”  mode.  A 
file  can  be  opened  and  shared  in  “read 
only”  mode  by  any  number  of  concurrent 
processes.  If  a  program  wishes  exclusive 
access  to  a  file,  it  can  open  it  in  “locked” 
mode;  the  operating  system  will  deny  any 
requests  by  other  tasks  to  open  the  same 
file. 


When  two  or  more  processes  share  a 
file  in  “unlocked”  mode,  both  having  the 
privilege  of  write  access,  there  is  a  poten¬ 
tial  danger  of  loss  of  information.  Consid¬ 
er  the  following  situation:  task  #1  reads 
a  record  from  the  disk  into  memory.  By 
coincidence,  task  #2  reads  the  same  rec¬ 
ord  immediately  thereafter.  Task  #1 
makes  some  changes  to  the  record  and 
writes  it  back  to  disk.  Task  #2  makes 
some  different  modifications  to  the  data 
and  writes  it  to  the  disk.  Depending  on 
which  task  happens  to  get  serviced  for  its 
disk  write  request  first,  one  or  the  other 
set  of  changes  will  be  permanently  lost. 
In  addition,  one  of  the  tasks  may  take 
some  erroneous  action  based  on  the  con¬ 
tents  of  the  disk  record  which  was  not 
yet  updated  by  the  other  task. 

The  capabilitycalled  “record-locking” 
is  designed  to  forestall  such  disasters  in  a 
multi-tasking  environment.  When  a  pro¬ 
gram  issues  a  read  request  fora  record,  it 
can  optionally  specify  that  the  record 
should  be  “locked,”  that  is,  the  record  is 
made  unavailable  for  updating  by  any 
other  process  until  it  is  released  by  the 
program  that  issued  the  “lock”  request. 


Table  II 

Concurrent  CP/M-86  function  calls.  Where  I  have  designated  console  functions  as  “compatible”  with  CP/M-86  or  MP/M, 
I  am  ignoring  issues  of  “virtual”  versus  “physical”  consoles.  Where  I  have  called  file  and  record  functions  “compatible”  with 
CP/M,  I  am  assuming  an  application  running  as  the  sole  task  and  disregarding  problems  of  file  or  record  sharing/locking. 


Function 

Action 

Function 

Action 

0 

% 

System  reset  — terminate  calling  process 

26 

+ 

Set  memory  address  for  disk  transfer 

I 

+ 

Console  input 

27 

+ 

Get  address  of  disk  allocation  table 

2 

+ 

Console  output 

28 

+ 

Write  protect  disk 

3 

# 

Raw  console  input 

29 

+ 

Get  disk  read-only  vector 

4 

# 

Raw  console  output 

30 

* 

Set  file  attributes 

5 

+ 

Output  to  default  list  device 

31 

+ 

Get  address  of  disk  parameter  block 

6 

* 

Direct  console  I/O 

32 

+ 

Set/get  user  code 

7 

# 

Get  I/O  byte  (not  implemented) 

33 

# 

Read  random  record 

8 

# 

Set  I/O  byte  (not  implemented) 

34 

# 

Write  random  record 

9 

+ 

Print  string 

35 

+ 

Compute  file  size 

10 

+ 

Buffered  console  input 

36 

+ 

Set  random  record 

11 

+ 

Read  console  status 

37 

+ 

Reset  disk  drive  (to  not  logged -in  state) 

12 

% 

Return  BDOS  version  number 

38 

# 

Access  drive  (place  on  lock  list) 

13 

% 

Reset  disk  system 

39 

# 

Free  drive  (remove  from  lock  list) 

14 

+ 

Select  disk 

40 

* 

Write  random  with  zero  fill 

15 

+ 

Open  file 

41 

# 

Test  and  write  record 

16 

+ 

Close  file 

42 

# 

Lock  record 

17 

+ 

Search  for  first  directory  match 

43 

# 

Unlock  record 

18 

+ 

Search  for  next  directory  match 

44 

# 

Set  multi-sector  transfer  count 

19 

+ 

Delete  file 

45 

# 

Set  BDOS  error  mode 

20 

+ 

Read  sequential 

46 

# 

Get  amount  of  free  disk  space 

21 

+ 

Write  sequential 

47 

# 

Chain  to  program 

22 

+ 

Make  file 

48 

# 

Flush  buffers 

23 

+ 

Rename  file 

49 

(not  implemented) 

24 

+ 

Return  log-in  vector 

50 

♦ 

Direct  BIOS  call 

25 

+ 

Return  current  disk 

51 

* 

Set  segment  address  for  disk  transfers 

22 
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This  allows  a  record  to  be  safely  modified 
by  one  program  without  fear  of  interfer¬ 
ence  by  other  tasks  that  may  be  execut¬ 
ing  simultaneously.  As  an  alternative  to 
file  and  record  locking  (which  consumes 
system  resources  and  can  slow  down  the 
system),  a  “Test  and  Write  Record”  func¬ 
tion  is  provided  which  verifies  that  the 
disk  copy  of  the  record  is  unchanged  be¬ 
fore  honoring  a  request  to  update  it. 

Additional  file  security  is  provided 
by  extensive  checksum  verification  of 
disk  directory  entries  and  all  active  file 
control  blocks.  This  is  designed  to  pre¬ 
vent  any  compromise  of  data  integrity  by 
a  task  which  has  crashed,  run  out  of  con¬ 
trol,  or  is  performing  disk  access  in  a  non¬ 
standard  manner.  It  should  be  noted 
that  some  techniques  of  file  access  which 
were  legal  under  earlier  versions  of  CP/M, 
especially  those  involving  direct  manipu¬ 
lation  of  the  file  control  block  or  simulta¬ 
neous  access  to  several  different  file  “ex¬ 
tents,”  are  intercepted  and  aborted  by 
Concurrent  CP/M-86  and  the  other  oper¬ 
ating  systems  which  use  the  third  genera¬ 
tion  BDOS. 

Even  with  the  safeguards  described 


above,  concurrent  access  to  multiple  files 
by  more  than  one  program  is  tricky  busi¬ 
ness.  It  requires  careful  analysis  and  a 
programmer  experienced  with  multi¬ 
tasking  operating  systems  in  order  to  be 
done  safely.  For  example,  it  is  quite  easy 
to  have  two  programs  get  into  a  “race 
condition”  where  each  has  locked  a  record 
that  the  other  needs,  and  thus  neither 
one  can  continue  to  execute  — system  re¬ 
sources  are  tied  up  irrevocably  and  usual¬ 
ly  the  operating  system  will  slow  down 
and  “die.” 

Executive  Services 

Concurrent  CP/M-86  offers  a  multi¬ 
tude  of  function  calls  for  use  by  the  ap¬ 
plication  programmer;  a  complete  list  of 
the  Concurrent  CP/M-86  operating  sys¬ 
tem  services  is  given  in  Table  II. 

In  addition  to  the  usual  functions 
1-40  which  are  present  in  ordinary  CP/M 
systems,  there  are  entire  new  repertoires 
of  capabilities  which  are  highly  reminis¬ 
cent  of  a  powerful  minicomputer  real¬ 
time  operating  system  such  as  DEC’S 
RSX-11M.  For  example,  functions  53 
through  58  and  128  through  130  allow  a 


program  to  dynamically  request,  use,  and 
release  memory  from  the  system  pool 
based  on  requirements  determined  at  run¬ 
time.  Functions  131  through  133  allow 
peripheral  device  drives  to  communicate 
with  other  tasks  through  use  of  “sema¬ 
phores”  or  software-controlled  flags. 

Functions  134  through  140  allow 
tasks  to  create  and  maintain  “queues,” 
which  can  be  used  to  pass  information 
asynchronously  between  processes.  Func¬ 
tions  146  through  149  and  158  through 
162,  among  others,  allow  a  given  program 
to  attach  or  detach  itself  for  input  and 
output  from  any  of  the  virtual  consoles 
or  printer  devices.  Functions  150  and  152 
assist  an  application  program  in  parsing 
filenames  and  interpreting  command  lines. 
Lastly,  function  144  allows  a  task  to 
initiate  or  “spawn”  other  processes  which 
can  run  concurrently. 

An  interesting  observation  in  passing 
is  that  BDOS  function  12,  which  fetched 
a  simple  one-byte  operating  system  ver¬ 
sion  number  in  CP/M-80,  has  been  drasti¬ 
cally  extended.  It  now  returns  a  sixteen- 
bit  parameter  that  is  broken  up  into  a 
number  of  bit  fields  to  specify  the  BDOS 


(Table  II  continued) 

Function 

Action 

Function 

Action 

52 

* 

Return  segment  address  for  disk  transfers 

142 

# 

Call  system  dispatcher 

53 

* 

Get  largest  available  memory  region 

143 

# 

Terminate  calling  process 

54 

* 

Allocate  maximum  memory  at  absolute  address 

144 

# 

Create  (spawn)  a  process 

55 

♦ 

Allocate  memory  segment 

145 

# 

Set  priority  of  calling  process 

56 

* 

Allocate  memory  segment  at  absolute  address 

146 

# 

Attach  console 

57 

* 

Free  memory  segment 

147 

# 

Detach  console 

58 

* 

Free  all  memory  segments 

148 

# 

Set  default  console  number 

59 

* 

Program  load 

149 

# 

Assign  console  to  another  process 

100 

# 

Set  directory  label 

150 

# 

Interpret  and  execute  a  command  line 

101 

# 

Return  directory  label 

151 

# 

Call  function  in  resident  procedure  library 

102 

# 

Read  extended  file  control  block 

152 

# 

Parse  filename 

103 

# 

Write  extended  file  control  block 

153 

# 

Return  number  of  default  console 

104 

# 

Set  date  and  time 

154 

# 

Get  address  of  System  Data  Area 

105 

# 

Get  date  and  time 

155 

# 

Get  date  and  time 

106 

# 

Set  default  password  for  file  access 

156 

# 

Return  address  of  process  descriptor 

107 

# 

Return  serial  number 

157 

# 

Abort  specified  process 

128 

# 

Memory  segment  allocation 

158 

# 

Attach  list  device 

129 

# 

Memory  segment  allocation 

159 

# 

Detach  list  device 

130 

# 

Free  memory  segment 

160 

# 

Select  default  list  device 

131 

# 

Poll  device  (test  logical  interrupt  flag) 

161 

# 

Conditionally  attach  list  device 

132 

# 

Wait  for  a  system  flag 

162 

# 

Conditionally  attach  console  device 

133 

# 

Set  a  system  flag 

163 

% 

Return  Concurrent  CP/M-86  version  number 

134 

# 

Create  system  queue 

164 

# 

Return  number  of  default  list  devices 

135 

# 

Open  queue 

136 

# 

Delete  queue 

137 

# 

Read  message  from  system  queue 

+ 

= 

compatible  with  CP/M-80,  CP/M-86,  and  MP/M 

138 

# 

Conditionally  read  message  from  queue 

* 

= 

compatible  with  CP/M-86  and  MP/M 

139 

# 

Write  message  into  system  queue 

# 

= 

compatible  with  MP/M-86 

140 

# 

Conditionally  write  message  into  queue 

% 

= 

similar  to  CP/M-86  or  MP/M,  but  with  subtle 

141 

# 

Delay  for  a  specified  number  of  clock  ticks 

differences 

23 

61 
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version,  the  environment  (whether  CP/M, 
Concurrent  CP/M,  MP/M,  or  any  of  the 
preceding  with  networking),  and  the  CPU 
type.  Digital  Research  is  evidently  plan¬ 
ning  well  ahead  here.  The  day  is  not  far 
off  when  the  entire  DRI  family  of  com¬ 
pilers  and  operating  systems  will  be  run¬ 
ning  on  the  8080,  Z-80,  8086/88,  68000, 
Z8000,  and  16000  microprocessors. 

Noteworthy  Features 

As  we  have  already  seen,  Concurrent 
CP/M-86  contains  much  that  is  new  and 
different  from  the  CP/M  systems  we  are 
all  accustomed  to,  but  there  are  a  few 
features  which  are  especially  welcome 
and  should  be  mentioned  here. 

•  File  access  has  been  enhanced  with  a 
special  “burst  mode,”  which  allows 
the  transfer  of  one  to  sixteen  records 
with  a  single  function  call. 

•  A  complete  set  of  BDOS  disk  error 
codes  are  defined,  and  an  application 
program  may  choose  to  handle  all  phy¬ 
sical  and  logical  disk  errors.  This  makes 
it  possible  for  editors,  disk  utilities, 
and  other  critical  programs  to  handle 
formerly  fatal  events  (such  as  the  disk 
drive  door  not  being  closed)  in  a  grace¬ 
ful  way.  The  dreaded  message,  “BDOS 
ERROR  ON  XX,”  which  has  been  the 
cause  of  so  much  cursing  by  users  and 
programmers  alike,  can  now  be  elimi¬ 
nated  forever. 

•  The  new  system  utilities,  DSKMAINT, 
CONFIG,  and  FUNCTION,  are  screen- 
oriented,  menu-driven,  make  extensive 
use  of  the  programmable  function  keys 
and  video  attributes,  and  are  practi¬ 
cally  idiot- proof.  I  hope  this  is  a  sign 
of  the  trend  to  be  taken  by  future 
Digital  Research  products. 

•  A  “virtual  disk”  capability,  sometimes 
known  as  “RAMDISK”or“M-DRIVE,” 
is  built  into  Concurrent  CP/M-86.  If 
the  operating  system  finds  that  the  sys¬ 
tem  has  memory  installed  at  the  prop¬ 
er  address,  the  virtual  disk  is  automat¬ 
ically  made  accessible  as  drive  “M:”. 
It  can  be  used  to  store  the  commonly 
needed  system  utilities  such  as  PIP  and 
STAT  and  any  temporary  files  created 
by  SUBMIT,  improving  the  perceived 
responsiveness  of  the  system  dramati¬ 
cally. 

Documentation 

The  manuals  for  Concurrent  CP/M-86 
demonstrate  a  quantum  jump  in  usability 
as  well  as  flashiness.  The  documentation 
is  divided  into  the  204-page  User’s  Manu¬ 
al  which  describes  operation  of  the  vari¬ 
ous  common  system  commands  and  utili¬ 
ties,  and  a  338 -page  Programmer’s  Guide 
which  covers  the  file  system  BDOS  func¬ 
tion  calls,  assembler,  and  debugger  in  de¬ 
tail.  Colored  text  is  employed  to  empha¬ 
size  example  of  actual  system  interac¬ 
tions.  Liberal  use  of  tables,  diagrams,  and 
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appendices  make  information  easy  to 
locate.  The  manuals  are  packaged  togeth¬ 
er  in  a  hardboard,  three-ring  binder  with 
accompanying  box  cover  that  is  slightly 
larger  than  the  IBM  format. 

As  is  usual  for  Digital  Research  docu¬ 
mentation,  the  manuals  are  aimed  at  a 
relatively  sophisticated  reader,  but  they 
are  well  organized  and  lucid.  There  are  a 
vanishingly  small  number  of  typographical 
and  grammatical  errors.  In  fact,  the  only 
technical  error  I  have  found  so  far  that 
might  affect  a  programmer  is  in  Appendix 
H  of  the  User’s  Guide ,  and  involves  an 
overlap  between  the  video  escape  sequence 
for  “Erase  Entire  Line”  and  “Insert  Blank 
Line.”  Clearly,  the  new  department  Digi¬ 
tal  Research  set  up  to  enforce  standards 
of  documentation  quality  has  made  its 
presence  felt. 

What  Price  Concurrency? 

With  320  Kbytes  of  main  memory,  I 
have  found  it  possible  to  run  three  64- 
Kbyte  tasks  simultaneously.  This  implies 
that  the  operating  system  with  its  various 
buffers  requires  about  128  Kbytes  of 
RAM.  The  load  image  “CPM.SYS”  on 
the  disk  drive  occupies  92  Kbytes. 

Naturally,  operating  system  support 
for  concurrent  task  execution  entails  a 
certain  amount  of  overhead  for  servicing 
the  system  clock,  maintaining  various 
queues  and  lock  lists,  saving  task  contexts, 
and  dispatching  tasks  based  on  their  pri¬ 
ority  and  demand  for  system  resources. 
To  try  to  assess  the  actual  effect  of  this 
overhead  on  task  execution  time,  I  ran  a 
well-known  Forth  prime  number  sieve 
benchmark  program  on  the  conventional 
IBM  implementation  of  CP/M-86  and  on 
Digital  Research  Concurrent  CP/M-86. 
This  is  a  classic  “CPU-bound”  program, 
with  no  disk  I/O  and  only  a  small  amount 
of  terminal  I/O.  The  program  completed 
in  27  seconds  on  ordinary  CP/M-86,  and 
in  28  seconds  on  the  Concurrent  version 
(with  no  other  active  tasks)— approxi¬ 
mately  a  4%  decrease  in  throughput.  It  is 
interesting  to  note  that  this  benchmark 
under  Microsoft  PC -DOS  requires  only 
25.7  seconds;  the  difference  can  probably 
be  attributed  to  the  time  which  is  wasted 
updating  the  status  line  display  on  IBM’s 
CP/M-86. 

Then  I  ran  the  same  CPU-bound 
benchmark  on  Concurrent  CP/M-86  as 
two  simultaneous  tasks.  They  each  com¬ 
pleted  in  56  seconds,  exactly  twice  the 
amount  of  time  required  when  the  bench¬ 
mark  executed  as  a  single  task.  This  im¬ 
plies  that  the  operating  system  overhead 
to  support  concurrency  is  relatively  inde¬ 
pendent  of  the  number  of  processes  that 
are  active. 

To  assess  the  effect  of  concurrent 
tasks  on  disk  performance,  I  coded  a  small 
routine  which  performed  100  random 
reads  of  1 -Kbyte  records  in  a  50-Kbyte 


contiguous  data  file.  This  is  a  truly  disk- 
I/O-bound  benchmark,  since  it  performs 
almost  no  computation  at  all  (except  for 
the  random  number  generator)  and  simply 
requests  one  disk  access  after  another.  On 
IBM’s  version  of  CP/M-86,  the  program 
completed  in  75  seconds  —a  surprisingly 
poor  performance.  On  Concurrent  CP/M- 
86,  with  one  task  running,  the  benchmark 
executed  in  52  seconds,  approximately  a 
30%  improvement!  However,  when  the 
system  was  really  put  to  the  acid  test 
with  two  copies  of  the  disk-bound  bench¬ 
mark  running  simultaneously  (accessing 
the  same  file  on  the  same  drive),  its  per¬ 
formance  really  fell  apart  and  each  task 
required  about  430  seconds  to  complete. 
This  seemed  to  be  largely  due  to  a  large 
amount  of  disk  “thrashing”  that  took 
place  as  the  two  tasks  requested  records 
in  different  extents,  forcing  many  inspec¬ 
tions  of  the  disk  directory. 

I  expect  that  the  most  common  use 
of  multi-tasking  by  the  average  user  will 
be  with  one  CPU-in tensive  program  such 
as  a  spreadsheet  or  word-processor  execu¬ 
ting  concurrently  with  spooling  of  a  file 
or  some  other  peripheral-bound  process. 
Under  such  circumstances,  the  decrease 
in  responsiveness  that  can  be  attributed 
to  multi-tasking  is  practically  unnotice- 
able.  To  verify  this  impression,  I  ran  the 
two  previously  described  types  of  bench¬ 
marks  simultaneously.  The  CPU-bound 
program  completed  in  32  seconds  and  the 
disk -bound  routine  finished  in  59  sec¬ 
onds,  each  showing  only  14%  degrada¬ 
tion  over  the  tasks  executing  alone. 

A  Few  Small  Gripes 

In  using  Concurrent  CP/M-86  for 
one  month,  I  have  not  found  any  earth- 
shaking  bugs  or  omissions.  There  are  a 
few  minor  annoyances  which  I  have  taken 
the  liberty  of  itemizing  below. 

There  is  no  check  for  the  disk  drive 
door  being  closed;  if  a  diskette  is  not 
loaded  into  a  drive  when  it  is  accessed, 
the  system  will  hang  indefinitely  without 
an  error  message. 

There  is  no  provision  for  accessing- 
the  bit-mapped  graphics  capabilities  of 
the  PC,  even  at  the  minimal  level  of  sim¬ 
ply  plotting  points.  Control  of  cursor 
position,  character  attributes,  selective 
erasing,  and  foreground  and  background 
colors  in  text  mode  is  provided  by  means 
of  escape  sequences— very  nice,  but  for 
unclear  reasons  the  character  underlining 
capability  fo  the  video  interface  was 
omitted  completely.  Furthermore,  Digital 
Research  did  not  choose  the  same  escape 
sequences  for  screen  control  as  were  used 
in  the  IBM  version  of  CP/M-86,  so  that 
vendors  of  program  packages  will  have  to 
maintain  and  sell  two  separate  versions. 

Output  to  the  video  screen  is  inexpli¬ 
cably  slow.  Text  appears  to  write  on  the 
screen  at  the  equivalent  of  somewhere 
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around  4800  baud.  I  realize  that  there  is 
unavoidable  overhead  involved  in  buf¬ 
fering  output  for  four  virtual  consoles. 
Still,  on  such  a  powerful  machine  with 
memory-mapped  video  to  boot,  one 
might  hope  for  a  somewhat  better  effec¬ 
tive  speed  of  display. 

The  state  of  the  CAPS  LOCK,  NUM 
LOCK,  and  WRAP  parameters  is  not 
maintained  individually  for  each  virtual 
console.  This  is  a  minor  point,  but  when 
you  are  flipping  back  and  forth  between 
an  editor  and  some  other  utility,  it  is  a 
nuisance  to  have  to  toggle  these  keys 
when  the  operating  system  could  just  as 
easily  keep  track  of  them  for  you. 

The  8086/88  assembler  does  not  in¬ 
clude  the  control  mnemonics  for  the 
Intel  8087  numeric  coprocessor.  Al¬ 
though  they  can  be  implemented  by  the 
user  with  the  CODE-MACRO  facility, 
this  is  a  very  laborious  process. 

The  system  boot  file,  startup  batch 
files,  and  all  of  the  commonly  used  sys¬ 
tem  utilities  will  fit  nicely  on  a  double¬ 
sided  disk  in  drive  A,  making  the  two- 
diskette  system  distributed  by  Digital 
Research  unnecessary.  But  even  if  every¬ 
thing  the  system  needs  is  on  drive  A  and 
no  auto-start  batch  files  are  present,  it 
will  still  try  to  access  drive  B  during  the 
cold  boot  sequence.  I  have  found  no  way 
to  configure  the  system  so  that  it  will 
leave  drive  B  alone. 


Summary 

Concurrent  CP/M-86  provides  the 
power  to  implement  applications  on  a 
desktop  machine  that  would  have  been 
unthinkable  even  two  or  three  years  ago. 
Even  for  the  casual  user,  the  flexibility 
and  conviences  that  will  result  from  the 
ability  to  execute  several  programs  con- 
curently  is  going  to  cause  a  rapid  “revolu¬ 
tion  of  rising  expectations”  that  will  have 
to  be  answered  by  the  other  manufactur¬ 
ers  of  microcomputer  operating  systems. 
I  rate  this  software  “Excellent.” 
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Program  Linkage  by 
Coroutines — Forth  to  BASIC 


Interactive  languages,  such  as  BASIC, 
normally  respond  to  commands  typed 
by  the  operator.  However,  there  are  sit¬ 
uations  in  which  it  might  be  desirable  for 
the  commands  to  be  issued  by  a  program, 
in  effect  making  BASIC  into  a  slave  of 
that  program.  This  can  be  accomplished 
by  incorporating  coroutines  in  the  I/O. 
The  method  is  a  general  one,  and  will  be 
illustrated  by  the  linkage  of  Forth  and 
BASIC,  in  which  Forth  is  the  driver  and 
BASIC  a  file  handler  and  floating-point 
calculator. 

The  particular  application  that  I  had 
in  mind  was  graphics  display  for  a  data 
base  in  microsoft  BASIC.  Forth  seemed 
ideal  for  the  purpose,  but  I  did  not  want 
to  lose  BASIC’s  file-handling  capabilities 
and  high-precision  floating-point  package. 
There  was  also  the  important  considera¬ 
tion  that  the  data  base  program  was  al¬ 
ready  written. 

The  problem  would  be  solved  if  1 
could  find  a  way  to  get  BASIC  to  accept 
commands  issued  by  Forth.  Then  Forth 
could  load  and  run  BASIC  programs. 
These  would  POKE  results  into  memory 
where  they  would  be  available  to  Forth. 

1  was  unable  to  work  out  a  method, 
until  I  saw  David  Shaw’s  note  on  corou¬ 
tines  (DDJ,  63:4,  January  1982).  Using 
that  principle,  1  solved  my  problem  in  a 
few  hours.  The  actual  implementation 
required  only  a  few  lines  of  code  incor¬ 
porated  in  the  I/O  segment  of  each  pro¬ 
gram. 

In  this  paper,  1  will  describe  the  gen¬ 
eral  principle,  followed  by  an  outline  of 
the  specific  application. 

Principle  of  Operation 

A  coroutine  can  be  thought  of  as  a 
separate  program  module  that  is  callable 
somewhat  like  a  subroutine.  Each  corou¬ 
tine  has  its  own  stack.  When  a  coroutine 
is  called,  the  coroutine  handler  pushes  the 
return  address  onto  the  current  stack, 
stores  the  stack  pointer  in  an  array,  and 
replaces  it  with  the  new  one.  Like  a  sub¬ 
routine,  a  coroutine  may  be  called  from 
anywhere  in  memory,  and  the  return  will 
be  to  the  memory  address  immediately 
following  the  call.  However,  a  return  is 
not  accomplished  by  a  RET  command, 
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but  rather  by  calling  the  original  program 
as  if  it  were  another  coroutine.  It  is  not 
necessary  to  return  directly  (or  for  that 
matter,  ever)  to  the  most  recent  calling 
program.  Therefore,  coroutines  do  not 
need  to  be  nested,  as  do  subroutines.  Co¬ 
routines  are  useful  in  multi-programming, 
interrupt  handling,  and  complex  I/O 
manipulation. 

In  the  method  used  here,  up  to  128 
coroutines  may  be  defined,  each  assigned 
a  number  divisible  by  2.  Coroutine  n  is 
called  by  the  sequence, 

MVI  A,n 

CALL  CSWAP  (see  below  for 
definition  of  CSWAP) 

The  coroutine  handler  has  two  en¬ 
tries,  CBEGIN  and  CSWAP.  (I  have  used 
these  names  to  avoid  confusion  with  the 
Forth  words,  BEGIN  and  SWAP.)  CBEGIN 
is  the  startup  entry.  CSWAP  is  called 
during  program  execution.  It  stores  the 
stack  pointer  of  the  current  program,  and 
substitutes  that  of  the  one  being  called. 
Any  registers  that  need  to  be  stored  must 
be  pushed  prior  to  calling  CSWAP,  and 
popped  on  return. 

Only  two  coroutines  are  required  for 
the  application  described  in  this  article. 
Coroutine  0  will  be  a  call  from  Forth  to 
BASIC,  and  coroutine  2  will  be  a  call 
from  BASIC  to  Forth. 

Linkage  is  accomplished  by  incorpo¬ 
rating  a  coroutine  call  in  the  I/O  segment 
of  each  program.  Emission  of  data  by 
Forth  is  handled  by  means  of  the  code 
shown  in  Listing  1.  The  byte  on  the  top 
of  the  stack  is  popped  into  register  E,  and 
then  register  E  is  moved  to  a  memory  lo¬ 
cation  named  CHAR.  Control  is  then 
transferred  to  BASIC  (actually  to  the 
North  Star  DOS)  via  coroutine  0. 

BASIC,  looking  for  input,  moves 
CHAR  to  the  A  register,  and  tests  it  (List¬ 
ing  2).  It  is  non-zero.  CHAR  is  now  set  to 
zero,  and  control  returns  to  BASIC  with 
the  most  recently  transmitted  character 
in  the  A  register. 

When  BASIC  needs  input  again,  it 
finds  that  CHAR  is  zero.  Control  is 
switched  to  Forth  via  coroutine  2,  where 
it  stays  until  Forth  is  ready  to  output 
another  character. 

Implementation 

My  system  is  a  SOL  with  North  Star 
disk  drives,  using  release  5.2  DOS,  in 
which  DOS  and  BASIC  can  be  relocated 
to  any  address.  By  careful  assignment,  it 


is  possible  to  get  all  of  the  necessary  pro¬ 
grams  into  memory  at  the  same  time. 


0  -7FFF 
8000 -BFFF 
C000 -CFFF 

D000 -DFFF 

E000 -E7FF 
E800 -EFFF 
F000 -FCFF 
FD00-FFFF 


FORTH 

BASIC 

COMPUTER  OPER¬ 
ATING  SYSTEM 
UTILITY  AND 
SCRATCH  AREA 
NOT  USED 
DISK  CONTROLLER 
DOS 

COROUTINES 


The  actual  implementation  required 
the  following  steps: 

1.  Assembling  the  coroutine  handler 
No  essential  changes  were  necessary 

to  Shaw’s  program,  but  1  have  simplified 
his  labeling  scheme  (Listing  5).  The  hand¬ 
ler  is  prefaced  by  a  jump  table  so  that  the 
entry  CBEGIN  is  at  ORG,  and  the  entry 
CSWAP  is  at  ORG+3.  The  parameter 
STAKSIZ  sets  the  amount  of  memory  to 
be  allocated  for  each  stack.  Since  both 
BASIC  and  Forth  set  their  own  stacks,  it 
can  be  set  to  a  low  value.  The  parameter 
GO  indicates  in  which  coroutine  the  pro¬ 
gram  will  start,  in  this  case  0. 

Stacks  are  defined  by  two  lines  of 
code  for  each  coroutine.  The  first  is  a  DS 
statement  that  allocates  room  for  the 
stack,  followed  by  a  DW  statement  labeled 
TnSTRT  which  contains  the  startup  ad¬ 
dress  for  the  coroutine.  In  the  application 
illustrated  in  this  paper,  two  coroutines 
are  defined,  labeled  T0STRT and  T2STRT. 
Next,  a  stack  table  is  defined  at  STAK- 
TAB.  Its  first  entry  is  T0STRT,  the  se¬ 
cond  T2STRT,  etc. 

2.  Modification  of  North  Star  DOS 
The  I/O  segment  of  the  North  Star 

DOS  needs  to  be  rewritten  to  incorporate 
the  code  in  Listing  2. 

3.  Loading  Forth  definitions 

The  Forth  screens  labeled  100  and 
101  (Listing  3)  define  Forth  words  that 
incorporate  the  code  in  Listing  1 .  Screen 
100  defines  various  addresses  as  constants, 
and  also  defines  CO-OUT,  a  Forth  word 
that  incorporates  the  output  code  in  List¬ 
ing  1.  The  CFA  (Code  Field  Address)  of 
EMIT  is  also  defined  as  a  constant  named 
EADDR.  EMIT  is  the  Forth  word  that 
sends  characters  to  the  console. 


In  screen  101,  the  words  [CO  and 
CO]  are  defined.  [CO  inserts  the  CFA  of 
CO-OUT  into  the  CFA  of  EMIT,  thus 
diverting  subsequent  output  to  the  co- 
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routine.  COl  replaces  the  original  value 
of  the  CFA.  These  words  also  set  and  re¬ 
set,  respectively,  the  two  flags  ISIG  and 
OSIG.  ISIG,  when  set,  forces  the  North 
Star  DOS  to  accept  input  from  the  co¬ 
routine  (see  Listing  2).  OSIG  suppresses 
all  DOS  output.  This  is  desirable  as  DOS 
and  BASIC  would  otherwise  echo  all 
commands.  These  flags  are  under  program 
control,  and  can  be  overridden  when 
necessary. 

The  word  [CO  causes  most  Forth 
output  words,  such  as  EMIT  .  .”,  etc.  to 
send  output  to  the  North  Star  DOS  via 
CO-OUT.  An  exception  is  CR  which,  in 
my  system,  causes  a  hang-up,  the  reasons 
for  which  are  unclear  to  me.  Instead,  I 
use  COCR,  defined  in  screen  101. 

4.  Starting  the  program 

To  start,  simply  jump  to  CBEGIN. 
Program  control  will  be  assumed  by  Forth. 

5.  Sample  program 

In  screen  102  (Listing  3),  an  example 
is  given.  It  defines  a  Forth  word  LOAD- 
XYZ  which  will  load  a  BASIC  program 
named  XYZ  and  then  transmit  the  num¬ 
ber  5  to  it.  The  program  XYZ  (Listing  4) 
simply  asks  for  the  input  of  a  number, 
and  inserts  it  at  RAM  address  52224 
(D000  hex).  Control  is  transferred  back 
to  Forth,  which  sets  the  number  from 
that  memory  address  and  prints  it. 

»»J 

(Listings  begin  on  page  28) 
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Listing  One  (Text  begins  on  page  26) 

Skeletal  Output  Module  for  Coroutine 


BYTE  TO  BE  TRANSMITTED  HAS  BEEN  POPPED  INTO 
THE  E  REGISTER 


LX  I  Hr CHAR 
MOV  Mr  E 
PUSH  B 
MV I  Ar  0 
CALL  CSWAP 
POP  B 
JMP  NEXT 


Move  byte  in  E  to  CHAR 
B  res  must  be  saved  in  FORTH 
Coroutine  0  cal  Is  BASIC 


Back  to  Forth 


Listing  Two 

Input  Module  for  Coroutine 


; SKELETAL  LISTING  FOR  N*  DOS  INPUT  ROUTINE 


ISIG 

EQU 

0F9FDH 

»  O=normalr  l=coroutine 

OSIG 

EQU 

0F9FEH 

t  O=norma 1 »  l=suppress 

CHAR 

EQU 

0F9FFH 

CSWAP 

EQU 

0FD03H 

; CINl  IS  NORTH  STAR  DOS  INPUT  ROUTINE 
i OBTAINS  CHARACTER  VIA  COROUTINE  IF  ISIG  NOT  0 
! OTHERWISE  FROM  KEYBOARD 
? CHARACTER  IS  RETURNED  IN  A  REGISTER 


CINl 

LDA  ISIG 

ORA  A 

JZ  KEYIN 

r 

If  ISIG=0  then  keyboard 

GETC1 

LX I  Hr  CHAR 

MOV  ArM 

r 

Move  CHAR  to  A-resister 

MVI  Mr  0 

r 

Reset  CHAR  to  0 

ORA  A 

RNZ 

Exit  if  there  was  a  b.yte 

MVI  A r  2 

f 

Otherwiser  to  FORTH  via 

CALL  CSWAP 

T 

coroutine  2 

JMP  GETC1 

7 

And  try  asaim  it's  there  now 

KEYIN 

♦  ♦  ♦  • 

r  Keyboard  input  routine  here 

•  •  ♦  ♦ 

RET 

28 


Dr.  Dobb’s  Journal,  Number  76,  February  1983 


Listing  Two  (Continued) 


; GOUT  IS  NORTH  OTAR  DOS  OUTPUT  ROUTINE. 

f NORTH  STAR  ENTERS  WITH  A  'DEVICE'  NUMBER  IN  REGISTER  A, 

:  BYTE  TO  BE  EMITTED  IN  REGISTER  B.  ON  EXIT.  A  MUST  CONTAIN 

?  A  COPY  OF  B. 

?  OS  I G  CONTROLS  ECHOING  OF  COMMANDS  BY  BASIC 
? IF  OS IG=1  THEN  OUTPUT  IS  SUPPRESSED 


?  Save  device  number  on  stack 


»  If  OSIG  is  O  then  norma  I  output 

;  N*  DOS  requires  this 
?  If  OSIG  is  non-0  then  no  output 


}  Regular  output  routine  here 
?  N*  DOS  resumes  this 


?  Set  CHAR  and  f lass-0 


Listing  Three 

Forth  Definitions 

<  SCREEN  100) 

HEX 

FOOO  CONSTANT  CBEGIN  (  STARTUP  ADDR  FOR  COROUTINE) 

CBEGIN  3  +  CONSTANT  CSWAP  (  CSWAP  ADDR  FOR  COROUTINE) 

F9FF  CONSTANT  CHAR  (  ADDR  OF  CHARACTER  TRANSMITTED) 

f  9FE  CONSTANT  OSIG  (  ADDR  OF  OUTPUT  SIGNAL) 

F9FD  CONSTANT  ISIG  (  ADDR  OF  INPUT  SIGNAL) 

CODE  CO- OUT 

D  POP  CHAR  H  LX  I  EM  MOV  B  PUSH 
0  A  MV I  CSWAP  CALL  B  POP  NEXT  J MR  Ci 

EMIT  OF A  CONSTANT  EADDR  (  CFA  of  EMIT  ) 


GOUT  PUSH  PSW 
LDA  OSIG 
ORA  A 
JZ  C0UT1 
PDF  PSW 
MOV  A. B 
RET 

CDIJT1  POP  PSW 


MOV  A  t B 
RET 

? INITIALIZATION 
TINIT  XRA  A 

STA  CHAR 
STA  OSIG 
STA  ISIG 
RET 
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Listing  Three  (Listing  continued,  text  begins  on  page  26) 

Forth  Definitions 

C  SCREEN  101) 

:  CCO  (  Insert  CFA  of  CO-OUT  into  CFA  of  EMIT;  set  flags) 
C  '  CO-OUT  CFA  3  LITERAL  EADDR  !  1  ISIG  C!  1  OSIG  C!  ; 

j  CO 3  (  Restore  CFA  of  EMIT  to  oris  value;  reset  ft  ass  ) 

C  EADDR  ©  3  LITERAL  EADDR  !  0  ISIG  C!  0  OSIG  C!  ; 

;  COCR  OD  EMIT  ;  '  Use  instead  of  CR  ) 

;  AC  3  EMIT  ;  (  Sends  c:tl-c  to  North  Star  DOS  ) 


(  SCREEN  102  EXAMPLE  ) 

(  ASK  NGRTHSTAR  DOS  TO  LOAD  BASIC  PROGRAM  XYZ  AND  RUN  IT) 
HEX 

;  LOADXYZ  CCO  . "  GO  BASIC  “  COCR 

. "  LOAD  XYZ  "  COCR 
.  ’■  RUN  "  5  .  COCR  CO  3  ; 

LOADXYZ  D000  C@  .  (  Should  print  5  ) 


Listing  Four 

Sample  BASIC  Program 


10  REM  SAMPLE  BASIC  PROGRAM  XYZ 

20  REM  INPUT  A  DIGIT  AND  POKE  IT  INTO  DOOO  HEX 

30  INPUT  I 

40  FILL  52224, I 

50  END 


Listing  Five 

Coroutine  Handler 

r 

; COROUTINE  HANDLER.  FOR  FULL  DOCUMENTATION. 
;SEE  TEXT  AND  DDJ  63; B,  JANUARY  1982 

r 

FDOO  ORG  OFDOOH 

r 

; JUMP  TABLE 

FDOO  C32CFD  JMP  CBEGIN 

FD03  C335FD  JMP  CSWAP 
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Listing  Five  (Continued) 


SET  PARAMETERS/  ALLOCATE  STACKSr  AND  SET  ENTRIES 


0008 

= 

STAKSIZ 

EQU 

8 

r 

SET  STACK  SIZE 

0000 

= 

GO 

EQU 

0 

f 

SET  STARTING  COROUTINE 

FD06 

DS 

STAKSIZ*2-2 

FD14 

0001 

TOSTRT 

DW 

100H 

r 

ENTRY  TO  FORTH 

FD16 

DS 

8TAKSIZ*2-2 

FD24 

2  QFO 

T2STRT 

DW 

0F028H 

6 

y 

ENTRY  TO  NORTHSTAR  DOS 

STACKTAB  IS  START  OF  ARRAY  FOR  STORAGE 


OF  STACK  POINTERS 
CURSTACK  POINTS  TO  CURRENT  POINTER 
IN  STACKTAB 


FD26 

14  FD 

STAKTAB  DW 

TOSTRT 

FD28 

24FD 

DW 

T2STRT 

F  D2A 

26FD 

CURSTAK  DW 

STAKTAB+GO 

FD2C 

2A2AFD 

y 

CBEGIN  LHLD 

CURSTAK 

FD2F 

7E 

MOV 

A/  M 

F  D30 

23 

INX 

H 

FD  31 

66 

MOV 

H/M 

FD32 

6F 

\  MOO 

Lt  A 

FD33 

F9 

SPHL 

F  D34 

C9 

RET 

FD35 

210000 

C SWAP  LX  I 

Ht  0 

FL'38 

39 

DAD 

SP 

FD39 

EB 

XCHG 

FD3A 

2A2AFD 

LHLD 

CURSTAK 

FD3D 

73 

MOV 

M*  E 

FD3E 

23 

INX 

H 

FD3F 

72 

MOV 

M/D 

F  D40 

CD4CFD 

CALL 

GETADDR 

FD43 

222AFD 

SHLD 

CURSTAK 

FD46 

5E 

MOV 

E*  M 

FD47 

23 

INX 

H 

FD48 

56 

MOV 

D/  M 

FD49 

EB 

XCHG 

FD4A 

F  9 

SPHL 

FD4B 

C9 

RET 

FD4C 

2126FD 

GETADDR  LX  I 

H/ STAKTAB 

F04F 

85 

ADD 

L 

F  D50 

6F 

MOV 

L*  A 

FD51 

DO 

RNC 

FD52 

24 

I  NR 

H 

FD53 

C9 

RET 

End  Listings 
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Linking  CPIM  Functions  to 
Your  High-Level  Program 


Abstract 

There  are  various  useful  operations 
generally  performed  by  the  operating  sys¬ 
tem  of  a  microcomputer  — directory  list¬ 
ing,  file  deletion,  and  other  file  manipula¬ 
tions.  Bringing  these  within  the  scope  of 
a  high-level  language  greatly  expands  a 
programmer’s  capabilities.  The  system 
functions  included  in  CP/M*  allow  short 
assembly  language  programs  to  be  linked 
to  programs  written  in  higher-level  lan¬ 
guages,  permitting  file  manipulation  dur¬ 
ing  program  execution.  The  program 
listed  here,  DEL,  can  be  used  to  delete 
files  during  the  execution  of  a  Fortran 
program,  and  is  based  on  the  two  CP/M 
functions,  Search  for  First  and  Delete 
File. 

11  CP/M  function  calls  are  made  in 
the  same  general  manner.  A  value 
identifying  the  function  desiicd  is 
loaded  into  register  C.  An  address,  if  ne¬ 
cessary,  may  be  loaded  into  DE,  identify¬ 
ing  the  location  of  required  information 
(for  instance,  the  name  of  a  file  to  be 
compared  to  directory  listings).  The  com¬ 
mand,  CALL  BDOS,  then  results  in  exe¬ 
cution  of  the  function. 

DEL,  the  assembly-language  program 
shown  in  Listing  One,  can  be  used  to 
delete  files  during  the  execution  of 
a  Fortran  program.  It  uses  two  of  these 
functions,  Search  for  First  and  Delete 
File.  The  short  Fortran  program,  shown 
in  Listing  Two,  illustrates  the  method  of 
calling  an  assembly-language  subroutine. 
CALL  DEL(NAME,NUM)  calls  the  sub¬ 
routine  DEL  and  places  the  address  of 
NAME  (the  filename)  in  HL  and  the  ad¬ 
dress  of  NUM  (the  output  parameter 
which  indicates  what  has  happened  to  the 
file)  in  DE.  During  execution  of  DEL, 
placing  the  desired  output  at  the  location 
initially  in  DE  then  ensures  that  the  varia¬ 
ble  NUM  will  contain  the  desired  output 
upon  return  to  Fortran. 

The  first  segment  of  DEL,  lines  7-15, 
saves  the  address  of  the  output  parameter 
and  sets  up  a  working  file  control  block 
(FCB).  The  subroutine  RO  then  calls  the 
function  Search  for  First  to  determine1 


by  Wendy  Weiger 


Wendy  A.  Weiger,  2816  Blazer  Court, 
Wheaton,  MD  20906. 


whether  the  file  specified  by  the  user  is 
actually  present.  If  not.it  returns;  if  pres¬ 
ent,  it  examines  the  ninth  byte  of  the 
filename  in  the  directory  to  determine  if 
it  is  read-only  (R/0).  A  nonexistent  or 
R/O  file  results  in  a  specific  value  being 
returned  in  the  accumulator:  FFH  if  the 
file  does  not  exist,  and  1  if  it  is  R/O.  If 
the  file  is  present  and  read/write  (R/W), 
the  subroutine  DELT  is  called  which  uses 
the  CP/M  function  Delete  File  to  delete 
the  file.  It  then  returns  0  in  the  accumula¬ 
tor.  Since  each  of  the  three  cases— nonex¬ 
istent,  R/O,  and  R/W  —  results  in  a  unique 
accumulator  value,  a  value  can  be  placed 
at  the  output  parameter  address  to  identi¬ 
fy  what  has  occurred  when  control  is  re¬ 
turned  to  the  high-level  language  calling 
program.  A  value  of  -1  indicates  a  nonex¬ 
istent  file;  0,  a  deleted  file,  and  1,  a  R/O 
file.  In  fact,  this  program  has  an  added 
advantage  over  the  system  ERA  command 
since  an  attempt  to  delete  a  R/O  file  does 
not  cause  the  system  to  suspend  opera¬ 
tion. 

It  should  be  noted  that  the  CP/M  De¬ 
lete  function  will,  in  case  of  an  ambiguous 
filename,  delete  all  files  that  fit  the  pat¬ 
tern  given.  However,  since  the  program 
DEL  is  designed  to  check  only  one  file¬ 
name  to  ensure  that  it  is  R/W,  an  attempt 
to  delete  several  files,  only  some  of  which 
are  marked  R/O,  may  generate  the  usual 
error  message  and  suspend  system  opera¬ 
tion.  A  more  extensive  program,  using 
both  the  Search  for  First  and  the  Search 
for  Next  functions  to  check  all  filenames 
that  fit  an  ambiguous  description,  could 
circumvent  this  problem. 

These  particular  programs  were  writ¬ 
ten  "using  an  Apple  II  computer  with  a 
Z-80  Softcard.  The  CP/M  operating  sys¬ 
tem  was  used,  along  with  the  Microsoft 
version  of  Fortran  and  assembly  language 
designed  for  the  M80  assembler  provided 
in  Microsoft’s  ALDS. 

The  program  DEL  demonstrates 
only  one  of  many  possible  combinations 
of  CP/M  system  functions.  A  large  num¬ 
ber  of  file  manipulations  can  be  performed 
within  the  context  of  higher-level  lan¬ 
guages  when  these  functions  are  used. 
Considering  the  space  limitations  of  mi¬ 
crocomputers,  their  potential  usefulness 
in  any  program  which  involves  the  crea¬ 
tion  or  alteration  of  large  data  files  is 
considerable. 


Editor’s  Note:  Wendy  Weiger  was  a  1982 
graduate  of  Harvard  in  chemistry.  She 
spent  the  summer  working  at  Lamont- 
Doherty  Geological  Observatory  of 
Columbia  University  on  a  geochemistry 
research  project.  While  there,  she  devel¬ 
oped  the  program  discussed  in  the  above 
article  to  be  used  in  conjunction  with  a 
statistical  analysis  package.  It  illustrates  a 
feature  of  CP/ M  that  would  be  valuable 
to  many  of  its  users. 


*CP/M  is  a  trademark  of  Digital  Research,  Inc. 
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Listing  One  —  DEL 


1 

ENTRY 

DEL 

: ON  ENTRY. HL  HAS  THE  FILENAME  ADDRESS, DE 

2 

: THE  OUTPUT  PARAMETER  ADDRESS 

3 

BDOS 

EQU 

05H 

; THESE  3  ADDRESSES  ARE  DEFAULT  VALUES 

4 

BUFF 

EQU 

8 1 H 

5 

FCB 

EQU 

05CH 

6 

DEL: 

LD 

< TEMP ) , DE 

: SAVE  ADDRESS  OF  2ND  (OUTPUT)  PARAMETEP 

8 

LD 

DE, FCB+1 

: WANT  TO  MOVE  FILENAME  TO  FCB+1 

9 

LD 

BC, 0BH 

: HL  HAS  FILENAME  ADDRESS,  1ST  INPUT  PARAM 

10 

LDIR 

: FILENAME  TO  FCB  BYTES  1-11 

1  1 

LD 

A,  OH 

12 

LD 

(FCB) . A 

!  3 

LD 

(FCB+12) , A 

14 

LD 

(FCB+15) , A 

15 

LD 

( FC3+32 ) , A 

; COMPLETES  WORKING  FCB 

16 

CALL 

RO 

; CHECKS  IF  FILE  PRESENT  AND  R/W 

17 

CP 

OFFH 

; WILL  BE  OFFH  IF  FILE  NOT  FOUND 

18 

JP 

2, LAST 

19 

CP 

0  1 H 

;WILL  BE  1  IF  FILE  R/O 

20 

CALL 

N2, DELT 

: DELETES  FILE  IF  PRESENT  AND  R/W 

21 

LAST: 

LD 

D.  A 

22 

LD 

E,  OH 

; VALUE  IN  A  MADE  INTO  2 -BYTE  QUANTITY 

23 

CP 

OFFH 

: OFFH  IF  FILE  NOT  FOUND 

24 

JP 

NZ. NEXT 

25 

LD 

E, OFFH 

; OUTPUT  WILL  BE  -1  IF  FILE  NOT  FOUND 

26 

NEXT: 

LD 

HL, (TEMP) 

; TEMP  HAS  ADDRESS  OF  OUTPUT  PARAMETEP 

27 

LD 

( HL  )  , D 

28 

INC 

HL 

29 

LD 

( HL ) , E 

30 

31 

32 

RET 

: ALL  DONE 

RO: 

LD 

C,  1 1H 

: TO  CHECK  IF  FILE  PRESENT  AND  R/W 

33 

LD 

DE. FCB 

: ENTER  CALLING  PARAMS  FOR  SEARCH  FOR  1ST 

3  4 

CALL 

BDOS 

35 

CP 

OFFH 

: OFFH  IN  A  IF  FILE  NOT  FOUND 

36 

RET 

Z 

: RETURNS  IF  FILE  NOT  FOUND. A  IS  FFH 

37 

ADD 

A,  A 

38 

ADD 

A,  A 

39 

ADD 

A,  A 

40 

ADD 

A.  A 

41 

ADD 

A,  A 

42 

LD 

C,  A 

43 

LD 

B,  00H 

44 

LD 

HL, BUFF 

: BUFF* (2**5) *A  GIVES  LOCATION  OF 

45 

ADD 

HL,  BC 

:  FILENAME  TAKEN  FROM  DIRECTORY 

46 

LD 

BC, OSH 

47 

ADD 

HL.  BC 

: ADDRESS  OF  9TH  BYTE  OF  FILENAME 

48 

LD 

A,  80H 

; 80H  IS  10000000B 

49 

AND 

(HL) 

: RESULT  1  IF  AND  ONLY  IF  FILE  R/0 

50 

RET 

Z 

; RETURNS  IF  FILE  FOUND  AND  R/W 

51 

LD 

A,  0 1 H 

: A  SET  TO  1  IF  FILE  R/C 

52 

FIN: 

RET 

53 

DELT: 

LD 

C,  13H 

: WILL  DELETE  FILE 

5  4 

LD 

DE. FCB 

: ENTER  CALLING  PARAMS  FOR  DEL  FUNCTION 

55 

CALL 

BDOS 

56 

LD 

A.  OH 

; A  SET  TO  0  IF  FILE  DELETED 

57 

RET 

58 

TEMP: 

DS 

2 

59 

END 

60 


Listing  Two  —  Calling  the 
Assembly-language  Routine 


1 : 

BYTE  NAME (11) 

2  * 

100 

FORMAT ( 11A1) 

3: 

200 

FORMAT ( 

ENTER  FILENAME:  S-CHAR  NAME, 3-CHAR  EXTENSION- 

-FILL'  / 

4  : 

U 

WITH 

BLANKS  IF  NECESSARY  TO  EXTEND  NAME  TO  8  CHARS 

( 1 1A1 ) ' / ) 

5: 

300 

FORMAT ( 

FILE  DELETED  / ) 

6: 

400 

FORMAT ( 

FILE  NOT  FOUND'/) 

7: 

500 

FORMAT ( 

FILE  R/O'/- 

8:  WRITE(3,200) 

9:  READ (3. 100) NAME 

10:  CALL  DEL ( NAME, NUM) 

11 :  IF ( NUM. EQ. -1 ) WRITE ( 3. 400) 

12:  I F ( NUM . EQ . 1 ) WR I TE ( 3 , 5  0  0 ) 

13:  IF ( NUM. EQ. 0 ) WRITE ( 3. 300  > 

14:  STOP 

1 5 :  END 

End  Listing 
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CP/M  EXCHANGE 


by  Gene  Head 


Last  month  I  mentioned  a  hot  DIR.- 
ASM  routine.  Well,  here  it  is.  DIR. ASM 
assembles  to  become  a  direct  replacement 
for  the  DIR  command  in  the  CP/M  CCP. 
DIR.COM  will  display  a  sorted  and  sized 
directory  along  with  space  and  directory 
entries  remaining  on  the  entire  disk.  DIR.- 
ASM  evaluates  hidden  (SYS)  files  as  well 
as  files  in  all  user  areas  when  computing 


space  and  directory  entries  remaining 
unused. 

CP/M  Function  #31  is  the  heart  of 
the  disk  sizing  code  and  should  make  this 
program  transportable  to  any  CP/M  system 
without  modification!  I  have  not  tested 
this  on  a  hard-disk  system  but  it  seems  to 
fly  OK  on  different  8”  and  5”  floppy 
machines. 


Bob  Blum  of  Norcross,  Georgia  has 
promised  a  follow-up  contribution  de¬ 
tailing  Function  #31  and  all  data  con¬ 
tained  in  the  Disk  Parameter  Block. 

Remember,  this  is  your  column. 
Make  a  contribution! 


DIR.ASM  Listing 


;  FROM:  HEAD  QUARTERS  -  CORVALLIS,  OREGON  97330 
;  FOR:  THE  CP/M  EXCHANGE 

;  DATE:  10-31-82  (FOR  JANUARY  ’82  ISSUE) 

9 

;  DIR.ASM 

■  THIS  PROGRAM  WILL  REPLACE  THE  DIR  COMMAND 
;  IN  THE  CP/M  CCP. 

•I 

;  YOU  CAN  NAME  THIS  PROGRAM  DIR.COM  AND  DISABLE 
;  THE  DIR  COMMAND  IN  THE  CCP  BY  DOING  A  ’GET’  SYSTEM 
;  SKIP  THE  ’PUT’  SYSTEM  BUT  DO  A  SAVE  xx  CPM.COM 
;  NOW  DDT  CPM.COM  AND  DUMP  MEMORY  UNTIL  YOU  SEE 
;  1  HE  ASCII  COMMANDS  DIR,  ERA,  TYPE,  REN.  CHANGE 

;  DIR  10  ’  D I  R>t  ’  THEN  ’PUT’  THE  MODIFIED  SYSTEM. 

9 

;  THE  SORTED  DIRECTORY  WILL  BE  DISPLAYED  WITH 
;  FILE  SIZES  IN  KILO-BYTES  AND  AMBIGUOUS  FILE 
;  REFERENCES  ARE  ACCEPTABLE  (*.*  ???????.???) 

;  THE  FOOTER  BANNER  WILL  LOOK  LIKE: 

•  DRIVE;  xn  FILES:  a  (b)  BYTES;  ck  <dk> 

9 

;  Where  x=dri ve,  n=user 

;  a=number  o+  Tiles  Found 

;  b=number  oT  directory  entries  available 

;  ck=ki 1 o— bytes  used  in  found  files 

;  dk=ki 1 o— bytes  remaining  unused  on  the  disk 

9 

;  R/O  FILES  ARE  DISPLAYED  USING  LOWER-CASE  LETTERS 


OPTIONALLY,  SPECIFIED  USER  AREAS  CAN  BE  DECLARED 
BY  PLACING  ONE  OR  TWO  DIGITS  IN  THE  SECOND  FCB. 

TO  SEE  ALL  THE  .COM  FILES  ON  DRIVE  B:  USER  AREA  4  TYPE: 

DIR  B : # . COM  4  <or>  DIR  B:*.COM  04 

UP  TO  15  USER  AREAS  ARE  SUPPORTED  IN  THIS  VERSION. 
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f  5  5  J 


5  J  * 
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ORB 


100H 


; DEFINE  THE  EQUATES 


; SYSTEM 
FCONOUT 

FUNCT 

EQU 

IONS 

n 

jL 

; CONSOLE  OUTPUT 

FSTRING 

EQU 

9 

; PRINT  STRING 

FVERS 

EQU 

12 

; RETURN  CP/M  VERSION 

FRESET 

EQU 

13 

; RESET  DISK  SYSTEM 

FSELDSK 

EQU 

14 

; SELECT  DISK 

FSEARCH 

EQU 

17 

; SEARCH  DIRECTORY 

FNEXT 

EQU 

18 

; SEARCH  NEXT  DIRECTORY 

FGETDSK 

EQU 

25 

; RETURN  CURRENT  DISK  DRIVE 

FDPB 

EQU 

31 

; GET  DPB  ADDRESS 

FUSER 

EQU 

32 

; GET  USER  NUMBER 

FSIZE 

EQU 

35 

; GET  FILE  SIZE 

; OTHER 

STUFF 

BDOS 

EQU 

5 

; BDOS  ENTRY  POINT 

FCB 

EQU 

5CH 

; FILE  PCONTROL  BLOCK 

FCB2 

EQU 

6CH 

; SECOND  FCB 

BUFF 

EQU 

SOH 

; DIRECTORY  BUFFER 

WR I TE 

EQU 

10 

; R/0  CODE  OFFSET 

RECNT 

EQU 

15 

; RECORD  COUNT  OFF-SET 

SYSTEM 

EQU 

9 

; SYSTEM  BYTE  OFF-SET 

MAXLINE  EQU 

-3 

; DISPLAYED  ENTRIES  PER  LINE 

CR 

EQU 

13 

; CARR I AGE  RETURN 

LF 

EQU 

10 

; LINE  FEED 

; BEG IN 

PROGRAM 

CODE 

START 

LX  I 

H,  0 

DAD 

SP 

SHLD 

STACK 

; SAVE  ENTRY  STACK 

LX  I 

SP, STACK 

MV  I 

C, FRESET 

CALL 

BDOS 

; CHECK  FOR  PROPER  VERSION  OF  CP/M 


MV  1 

C, FVERS 

CALL 

BDOS 

CPI 

20 

LX  I 

D, BADVER 

;  BAD  VERSION 

JC 

EXIT 

;  EXIT  IF  NOT 

; INITIALIZE  THE  DISK,  THE  USER,  AND  THE  FCB 
CALL  INITIALIZE 


(Continued  on  next  page) 
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DIR.ASM  Listing  (Listing  continued,  text  begins  on  page  34) 


; DETERMINE  SPACE  REMAINING  ON  DISK 
; AND  REMAINING  DIRECTORY  ENTRIES 


CALL 

CAPACITY 

; COMPUTE  DISK  CAPACITY 

;  READ 

SELECTED 

ENTRIES  FROM  DIRECTORY  INTO  BUFFER 

CALL 

RESET 

; RESET  THE  BUFFER  POINTER 

CALL 

READ 

; READ  IN  SELECTED  DIRECTORY 

;  SORT 

SELECTED 

INTRIES  IN 

THE  BUFFER 

CALL 

RESET 

; RESET  BUFFER  POINTER 

CALL 

SORT 

;  SORT  THE  DIRECTORY 

; DISPLAY  SORTED 

,  SELECTED 

ENTRIES  FROM  THE  BUFFER 

CALL 

RESET 

; RESET  THE  BUFFER  POINTER 

CALL 

DISPLAY 

; DISPLAY  SORTED  DIRECTORY 

; DISPLAY  DISK  CAPACITY  AND  FILES/SPACE  USED 

LX  I 

D, FOOTER 

; POINT  TO  FOOTER  BANNER 

; DISPLAY  MESSAGE  POINTED 

TO  BY  DE  THEN  EXIT 

EXIT 

MV  I 

C, FSTRING 

CALL 

BDOS 

LDA 

USERC 

MOV 

E,  A 

MV  I 

C, FUSER 

CALL 

BDOS 

LHLD 

STACK 

SPHL 

; RESTORE  ENTRY  STACK 

RET 

; . .  .  THEN  EXIT 

******************************* 

*  SUBOUTINES  FOLLOW  * 

******************************* 

; INITIALIZE  DISK,  USER,  AND  FCB 

•  / 

INITIALIZE  EQU  * 

;  GET  TO  THE  PROPER  DRIVE  IF  NOT  DEFAULT  DRIVE 


LDA 

FCB 

ORA 

A 

PUSH 

PSW 

MOV 

E,  A 

DCR 

E 

POP 

PSW 

MV  I 

C, FSELDSK 

CNZ 

BDOS 
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;  NOW  GET  THE  SELECTED  DISK  (IT  MIGHT  BE 
; THE  DEFAULT  DRIVE)  AND  SAVE  IT  AT  ’DRIVE’ 


MV  I 

C, FGETDSK 

CALL 

BDOS 

STA 

DISK 

ADI 

’A’ 

;  MAKE 

IT 

ASCI  I 

STA 

DRIVE 

;  SAVE 

IT 

IN  FOOTER 

; NOW  GET  THE  USER  NUMBER,  CONVERT  IT  TO  DECIMAL, 

; SAVE  IT  AT  ’USER’ 

MV I  C, FUSER 

MV I  E , OFFH 

CALL  BDOS 

STA  USERC  ; SAVE  CURRENT  USER 

LHLD  FCB2+1  ; GET  ASSIGNED  USER 

MOV  A, L 

CPI  ’  ’ 

JNZ  PASTY 

MOV  A, H 

CPI  ’  ’ 

JZ  F'ASTX  ;  NO  NEW  USER  GIVEN 

PASTY  CALL  DEC2BIN  ; CONVERT  ASCII  TO  BINARY 

STA  USERX  ; SAVE  ASSIGNED  USER 

MOV  E, A 

MV I  C, FUSER 

CALL  BDOS  ;  SET  NEW  USER 

PASTX  LDA  USERX 

MOV  L, A 

MV I  H, O 

LX  I  D , USER  ;  SAVE  ASCII  DECIMAL 

CALL  XXDECIMAL  ; IN  FOOTER  BANNER 


;  FILL  IN  THE  FCB  WITH  ’?’s  IF  IT  IS  EMPTY 


LDA 

FCB+1 

CPI 

?  J 

LX  I 

D, FCB+1 

LX  I 

H, DUMMY 

;  DUMMY  FCB  IS  ’ 

MV  I 

B,  11 

CZ 

M0VH2D 

RET 

; CONVERT  ASCII 

CHARACTERS 

IN  HL  TO  BINARY  VALUE  IN  A 

5 

—  > 

DEC2BIN 

EQU 

$ 

MOV 

A,  H 

CPI 

*  > 

; IS  THIS  SINGLE  DIGIT? 

JNZ 

DOl 

MOV 

H,  L 

; CONVERT  SINGLE  DIGIT  TO 

MV  I 

L,  0 

; DOUBLE  DIGIT  LIKE  1=01 

DOl 

MOV 

A,L 

SUI 

’  O’ 

;  MAKE  BINARY  (Continued  on  next  page) 
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DIR. ASM  Listing  (Listing  continued,  text  begins  on  page  34) 


AN  I 

1 

MV  I 

B,  0 

JZ 

D02 

MV  I 

B ,  1 0 

;  ADD  10  IF  >  9 

D02 

MOV 

A,  H 

SUI 

'  O’ 

;  MAKE  BINARY 

ADD 

B 

CPI 

16 

;  TEST  FOR  MAX  OF  15 

RC 

; RETURN  IF  <  16  ELSE 

LDA 

USERC 

S _ DEFAULT  TO  CURRENT  USER 

RET 

1 

; RESET 

THE  DIRECTORY  BUFFER  POINTER 

; THE  TO 

TOP 

OF  THE  DIRECTORY 

BUFFER 

9 

RESET 

EQU 

LX  I 

H, BUFFER 

SHLD 

RET 

DIRBUFP 

; DISPLAY  THE 

BUFFER  (MAXLINE) 

WIDE 

DISPLAY 

EQU 

* 

LDA 

SFILES 

ORA 

A 

JNZ 

DISP1 

; TEST  FOR  EMPTY  BUFFER 

LX  I 

D.NOENT 

MV  I 

C,  FSTRING 

CALL 

RET 

BDOS 

DISP1 

LX  I 

H, XXNUL 

MV  I 

M,  ’  ’ 

; DISPLAY  LEADING  ZEROS 

LX  I 

H,  0 

; . . . AS  BLANK  SPACES  (JUSTIFY) 

SHLD 

TSIZE 

SHLD 

TFILES 

CALL 

NEWLINE 

D1 

PUSH 

B 

LHLD 

DIRBUFP 

PUSH 

H 

; SAVE  CURRENT  POINTER 

LDA 

XXRECL 

MV  I 

D,  0 

MOV 

Ej  A 

DAD 

D 

; GET  NEXT  RECORD  POINTER 

SHLD 

D I RBUFP 

; SAVE  NEXT  ENTRY  POINT 

DCX  H  ; GET  TO  CURRENT  RECORD  SIZE 

; DISPLAY  R/O  FILES  AS  LOWER  CASE  ASCII 

DCX  H!  DCX  H!  DCX  H  ;  GET  TO  THE  R/O  BYTE 

MOV  A, M  ; _ AND  SAVE  IT  IN  ’A’ 
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RAR! 

RAR 

AN  I 

2  OH 

; SET  LOWER  CASE  MASK 

STA 

MASK 

; IF  READ/ONLY  FILE 

INX 

H!  INX  H '  INX 

H  ; GO  BACK  TO  RECORD  COUNT 

; CHECK  FILE 

SIZE  FOR  ZERO 

MOV 

L,M 

;  S I ZE  IN  HL 

MV  I 

H,  0 

MOV 

A,L 

ORA 

A 

; IF  SIZE  IS 

ZERO  THIS  IS  EITHER  A  NULL  FILE  OR  A 

; FILE  WITH  A 

RECORD  COUNT  OF 

80H. 

: IN  EITHER  CASE  BO  USE  THE  6ETSIZE 

; SUBROUTINE 

TO  PROPERLY  SIZE 

THE  FILE. 

CZ 

GETSIZE 

XCHG 

LHLD 

TSIZE 

; SUM  TOTAL  SIZE 

DAD 

D 

SHLD 

TSIZE 

LHLD 

TFILES 

INX 

H 

SHLD 

TFILES 

; BUMP  FILE  COUNTER 

XCHG 

LX  I 

D,KSIZE 

5 

SAVE  FILE  SIZE 

CALL 

XX DECIMAL 

5 

_ IN  K-BYTES 

POP 

H 

5 

RESTORE  DIRECTORY  POINTER 

MV  I 

C,  8 

CALL 

NPRINT 

5 

FILE  NAME 

MV  I 

E,’  ’ 

CALL 

PRINT 

5 

_ SPACE 

MVI 

C  j  3 

CALL 

NPRINT 

5 

. TYPE 

XRA 

A 

STA 

MASK 

5 

CLEAR  LOWER-CASE  MASK 

LX  I 

H, KSI ZE+1 

MVI 

C,5 

CALL 

NPRINT 

5 

. SIZE 

POP 

B 

; GET  WIDTH  COUNTER 

DCR 

B 

JNZ 

D2 

(Continued  on  next  page) 
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DIR. ASM  Listing  (Listing  continued,  text  begins  on  page  34) 


;  GET 

HERE  ONLY 

AFTER  LAST 

ENTRY  PER  LINE 

CALL 

NEWLINE 

CALL 

BUMP 

JNZ 

D1 

JMP 

BAN1 

;  GET 

HERE  AFTER 

ANY  ENTRY 

OTHER  THAN  LAST  PER  LINE 

D2 

LX  I 

H, OLDL 

MOV 

C,  M 

INX 

H 

CALL 

NPRINT 

;  GET 

HERE  AFTER 

EACH  DISPLAYED  ENTRY 

D3 

CALL 

BUMP 

JNZ 

D1 

CALL 

NEWLINE 

JMP 

BAN1 

BUMP 

LDA 

SFILES 

; COUNT  DOWN  ENTRY  COUNTER 

DCR 

A 

STA 

SFILES 

RET 

; START  A  NEW  DISPLAY  LINE 

AND  INITIALIZE  WIDTH  COUNTER 

NEWLINE  MV I 

E ,  CR 

CALL 

PRINT 

MV  I 

E,LF 

CALL 

PRINT 

MV  I 

B, MAXLINE 

RET 


s - > 

CAPACITY  EQU  * 

; USING  THE  CP/M  FUNCTION  TO  ACCESS  THE  DISK  PARAMETER  BLOCK, 

; FIND  MAX  DISK  SPACE,  MAX  DIRECTORY  ENTRIES 

; SEE  PAGE  27  OF  CP/M  ALTERATION  GUIDE  (C)  DIGITAL  RESEARCH  1979 


BLS 

BSH 

BLM 

1024 

3 

7 

2048 

4 

15 

4096 

5 

31 

8192 

6 

63 

16384 

7 

127 

MV  I 

C, FDPB 

; RETURN  DISK  PARAMETER 

CALL 

BDOS 

I  NX 

H 

INX 

H 

MOV 

A,  M 

;  GET  SHIFT  FACTOR  BSH 

DCR 

A 

42 
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SIZE1 


SIZE2 


DCR 

A 

STA 

BSH 

INX 

H 

MOV 

A,  M 

; GET  BLM 

STA 

BLM 

INX 

H 

; SKIP  EXM  BYTE 

PUSH 

H 

; SAVE  DPB  POINTER 

LX  I 

H, 1024/2 

LDA 

BSH 

; GET  SHIFT  FACTOR 

DAD 

H 

DCR 

A 

JNZ 

SIZE1 

SHLD 

BLS 

; BLS  =  512  *  (  (BSH-2) 

POP 

H 

; RESTORE  DPB  POINTER 

INX 

H 

MOV 

E,M 

INX 

H 

MOV 

D,M 

; GET  DOUBLE  BYTE  DSM 

INX 

D 

INX 

H 

XCHG 

SHLD 

XCHG 

DISKSIZ 

; SAVE  DSM 

MOV 

E  5  M 

INX 

H 

MOV 

XCHG 

D,  M 

; GET  DOUBLE  BYTE  DRM 

INX 

H 

; MAXENT  =  DRM  +  1 

SHLD 

MAXENT 

; SAVE  MAX  DIR  ENTRIES 

DAD 

H 

; COMPUTE  TOTAL  SPACE 

DAD 

H 

REQUIRED  FOR 

DAD 

H 

; . . . -THE  DIRECTORY 

DAD 

H 

; 32  BYTES  PER  ENTRY 

DAD 

H 

; OR  (DRM+1 ) *32 

XCHG 

LHLD 

BLS 

DCX 

H 

DAD 

D 

LDA 

BSH 

; COMPUTE  NUMBER  OF 

MOV 

C,  A 

; . . BLOCKS  THAT  HAVE 

MOV 

A,  H 

;  .  .  . . BEEN  RESERVED  FOR 

RAR 

; . THE  DIRECTORY 

AN  I 

RAR 

7EH 

DCR 

C 

JNZ 

SIZE2 

44 
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DIR.ASM  Listing 

(Listing  continued,  text  begins  on  page  34) 

CMA 

MOV 

C,  A 

MV  I 

B, OFFH 

INX 

B 

LHLD 

DISKSIZ 

; SUBTRACT  DIRECTORY  SPACE 

DAD 

B 

LDA 

BSH 

BIZE3 

SHLD 

DISKSIZ 

; SAVE  TOTAL 

REMAINING 

SPACE 

DCR 

A 

JZ 

READALL 

DAD 

H 

JMP 

SIZE3 

SIZE4 

SHLD 

DISKSIZ 

;  SAVE  TOTAL 

SPACE  FOR 

FILES 

READALL 

MV  I 

C, FSEARCH 

LOOP1 

LX  I 

D, DUMMY 

MV  I 

A,  *  ?' 

; SEARCH  EVERY  DIRECTORY  ENTRY 

STAX 

D 

CALL 

BDOS 

ORA 

A 

; END  OF  DIRECTORY? 

JM 

BANNER 

; GO  FILL  THE  BANNER 

CALL 

SIZFIL 

JZ 

LOOP2 

LHLD 

TFILES 

INX 

H 

; COUNT  EVERY  ENTRY 

SHLD 

TFILES 

LHLD 

TSIZE 

DAD 

B 

; ADD  UP  TOTAL  SPACE  USED 

SHLD 

TSIZE 

L00P2 

MV  I 

C, FNEXT 

JMP 

LOOP1 

; FILL  BANNER 

WITH  DISK  CAPACITY 

INFO 

BANNER 

EQU 

$ 

XRA 

A 

STA 

XXNUL 

LHLD 

TFILES 

XCHG 

LHLD 

MAXENT 

CALL 

XXDMINUS 

DAD 

D 

LX  I 

D,FREEF 

CALL 

XXDECIMAL 

; SHOW  FREE  FILES 

LHLD 

TSIZE 

XCHG 

LHLD 

DISKSIZ 

• 

CALL 

XXDMINUS 

DAD 

D 

LX  I 

D, FREEB 

CALL 

RET 

XXDECIMAL 
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; FILL  BANNER  WITH  SELECTED  FILE  INFO 


BAN1 


EQU 

$ 

XRA 

A 

ST  A 

XXNUL 

LHLD 

TFILES 

LX  I 

D, FILES 

CALL 

XX DECIMAL 

LHLD 

TSIZE 

LX  I 

D , BYTES 

CALL 

RET 

XXDECIMAL 

; GET  THE  SIZE  OF  THE  FOUND  FILE 

.  > 

SIZFIL:  EQU  $ 


;  CALLED  I  IMMEDIATELY  AFTER  A  SUCCESSFUL  SEARCH 
;  OR  SEARCH  NEXT  FUNCTION  CALL. 

; ON  EXIT: 

; HL  POINTS  TO  THE  FILE  IN  THE  DIRECTORY. 

; BC  HOLDS  THE  KILO-BYTE  FILE  SIZE. 

; ZERO  SET  =  SKIP  ALL  DELETED  FILES. 

; CARRY  SET  =  FULL  EXTENT  (COUNT  ENTRY  BUT  DON’T  SIZE) 
;  ZERO  ?<  CARRY  CLEAR  =  COUNT  THE  ENTRY  AND  SIZE  IT 


LX  I 

B,  O 

; ASSUME  ZERO  FILE  LENGTH 

LX  I 

H , BUFF 

; DIRECTORY  BUFFER 

AN  I 

03 

;  0-3 

RRC ! 

RRC !  RRC 

; A=A*32 

ADD 

L 

MOV 

L,A 

PUSH 

H 

; HL  POINTS  TO  FOUND  FILE 

MOV 

A,  M 

ORA 

A 

S CLEAR  THE  CARRY  FLAG 

CPI 

0E5H 

; CHECK  THE  ZERO  FLAG 

JZ 

SKI PALL 

; SK I P  DELETED  ENTRIES 

LX  I 

D , RECNT 

; RECORD  COUNT  FIELD 

DAD 

D 

MV  I 

A,  7FH 

ANA 

M 

JZ 

3KIFSIZ 

; SKIP  SIZE  OF  EXTENDED  FILES 

MOV 

B,M 

LDA 

CMA 

BLM 

MOV 

CMA 

C,  A 

ADD 

B 

ANA 

r 

RRC  ' 

RRC !  RRC 

AN  I 

i  FH 

; K— BYTES  IN  RECORD  COUNT 

MOV 

C,  A 

;  .  .  .OF  LAST  EXTENT  (Continued  on  next  page) 
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DIR.ASM  Listing 

(Listing  continued,  text  begins  on  page  34) 

DCX 

H 

DCX 

H 

; BACK  UP  TO  EXTENT  BYTE 

DCX 

H 

MOV 

A ,  M 

; GET  NUMBER  OF  EXTENTS 

RLC  ! 

RLC !  RLC !  RLC 

5 

AN  I 

OF  OH 

ADD 

c 

MOV 

M,  A 

; SI ZE  IN  K-BYTES  IN  EX  FIELD 

MOV 

C,  A 

MV  I 

B,  O 

; FILE  SIZE  IN  BC 

XRA 

A 

; CLEAR  CARRY 

SKI PS I 2  I NR 

A 

; NON-ZERO 

SKI PALL  POP 

RET 

H 

; HL  POINTS  TO  DIRECTORY  ENTRY 

;  USE  CF'/M  FUNCTION  #35  TO  GET 

THE  ACTUAL  FILE  SIZE 

!» 

6ETSIZE  EGU 

$ 

; ON  ENTRY  HL  POINTS  TO  A  FILE 

IN  THE  BUFFER 

; ON  EXIT  HL=F ILE  SIZE  IN  K-BYTES 

POP 

B !  POP  D 

; GET/SAVE  START  OF  BUFFER 

PUSH 

D !  PUSH  B 

; _ ENTRY  IN  DE 

LX  I 
XCHG 

H , DUMMY 

PUSH 

H !  PUSH  D 

INX 

D 

; PASS  UP  DRIVE  FIELD 

MV  I 

B,  12 

CALL 

M0VH2D 

; FILL  DUMMY  WITH  FILE  TO  SIZE 

POP 

D !  POP  H 

PUSH 

D !  PUSH  H 

MV  I 

C,  FSIZE 

; SI ZE  THE  FILE 

CALL 

BDOS 

POP 

H 

POP 

XCHG 

D 

LHLD 

DUMMY+33 

; MAKE  SIZE  =  K-BYTES 

MOV 

A,  L 

AN  I 

7 

PUSH 

PSW 

MOV 

A,  L 

RAF: ! 

RAR !  RAR 

AN  I 

1FH 

MOV 

L ,  A 

MOV 

A,  H 

RAL  ! 

RAL !  RAL ! 

RAL !  RAL 

AN  I 

OEOH 

ORA 

L 

MOV 

L,  A 

MOV 

A,  H 

RAR  ! 

RAR i  RAR 

AN  I 

1FH 

MOV 

H,  A 

POP 

RZ 

PSW 

INX 

RET 

H 

; ADD  ONE  IF  OVER-FLOWED 
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; READ  EACH  DIRECTORY  ENTRY  INTO  THE  DIRECTORY  BUFFER 
!  " 

READ  EQU  $ 

;HL  FOINTS  TO  THE  DIRECTORY  ENTRY  OF  12  CHARACTERS 
; 1 —8  FILE  NAME,  9-11  FILE  TYPE,  12  FILE  SIZE  IN  K-BYTES 


READ1 


READ2 


LX  I 

H ,  0 

SHLD 

TFILES 

; CLEAR  FILE  COUNT 

SHLD 

TSIZE 

; CLEAR  TOTAL  SIZE 

MV  I 

C, FSEARCH 

LX  I 

D,  FCB 

CALL 

BDOS 

ORA 

RM 

A 

5  EX  IT  IF  NO  FILES 

CALL 

SIZFIL 

JZ 

READ2 

5  SKIP  DELETED  FILES 

JC 

READ2 

5  SKIP  FULL  EXTENTS 

LDA 

USERX 

CMP 

M 

JNZ 

READ2 

3  SKIP  NON-CURRENT  USER 

INX 

H 

; PAST  DR  FIELD 

PUSH 

H 

LX  I 

D, SYSTEM 

3  LOOK  AT  SYSTEM  BYTE 

DAD 

D 

MOV 

RLC 

A,  M 

POP 

H 

JC 

READ2 

5  SKIP  SYSTEM  FILES 

PUSH 

H 

LHLD 

DIRBUFP 

3  GET  CURRENT  OUTPUT 

XCHG 

5  POINTER  IN  DE 

LX  I 

H,  12 

5  BUMP  TO  NEXT  ENTRY 

DAD 

D 

SHLD 

DIRBUFP 

5  SAVE  NEXT  POSITION 

LX  I 

H, SFILES 

I  NR 

M 

3  COUNT  FILES  IN  BUFFER 

POP 

H 

; HL=SOURCE  DE=DEST I NAT 

MV  I 

B,  12 

CALL 

M0VH2D 

MVI 

C,  FNEXT 

JMP 

READ1 

3  DEC I M AL  CONVERS I ON 


XX DECIMAL:  EQU  $ 

;  FROM  DAVE  FRIEDMAN’ S  SLOT  MACHINE  PROGRAM 
;  DDJ  #50  NOV /DEC  1980 


(Continued  on  next  page) 
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DIR. ASM  Listing  (Listing  continued,  text  begins  on  page  34) 
j THIS  SUBROUTINE  CONVERTS  THE  VALUE  IN  (HL) 

; TO  DECIMAL  ASCII  AND  STORES  THE  CHARACTERS 
; LEFT  JUSTIFIED  (NO  LEADING  SPACES  OR  ZEROS) 

; TO  THE  CONSECUTIVE  MEMORY  LOCATIONS  POINTED 
; TO  BY  (DE> . 

; ALL  REGISTERS  ARE  PRESERVED 

; ALL  LABELS  ARE  ’ XXLABEL7  TO  AVOID  COFLICT 
5  IN  EXISTING  LABELS. 

PUSH  H!  PUSH  D!  PUSH  B!  PUSH  PSW 


MV  I 

B,  0 

? 

SUPRESS  LEADING 

PUSH 

D 

LX  I 

D , - 1 OOOO 

CALL 

XXDIV 

POP 

D !  STAX 

D  ! 

INX 

D! 

PUSH 

D 

LXI 

D , - 1 OOO 

CALL 

XXDIV 

POP 

D !  STAX 

D  ! 

I  NX 

D! 

PUSH 

D 

LXI 

D , - 1 OO 

CALL 

XXDIV 

POP 

D 1  STAX 

D' 

INX 

D  ! 

PUSH 

D 

LXI 

D,  -10 

CALL 

XXDIV 

FOF' 

D!  STAX 

D' 

INX 

D! 

PUSH 

D 

LXI 

D,  — 1 

CALL 

XXDIV 

POP 

D 

LDA 

XXNUL 

CMP 

C 

MOV 

A,  C 

JNZ 

XXLASTD 

MV I  A , ’O’  ; SHOW  AT  LEAST  ONE  ZERO 

XXLASTD  STAX  D 

POP  PSW !  POP  B !  POP  D !  POP  H 
RET 


XXDIV  MV I  C,’0'-1 

XXDIV1  INR  C 

DAD  D 

JC  XXDIV1 

CALL  XXDMINUS 

DAD  D 

MOV  A,  C 

ORA  B 

MOV  B, A 

CPI  ’O’ 

JNZ  XXSURP 

LDA  XXNUL 

MOV  C , A 

XXSURP  MOV  A, C 

RET 
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; MAKE  DE=DE*-1 

FOR 

DOUBLE 

SUBTRACTION 

XXDMINUS 

EQU 

$ 

MOV 

A,  E 

!  CMA 

!  MOV  E, A 

MOV 

A,  D 

!  CMA 

!  MOV  D, A 

I  NX 

D 

RET 

; SOR  T  THE  BUFFER 

; - > 

SORT  EQLI  $ 

;  FROM  INTERFACE  AGE  NOV -78  -  CHRIS  TERRY 


XX SORT  EQU 
EDA 
MV  I 
MOV 
CALL 
LHLD 
DAD 
SHLD 
LDA 
MOV 

XXNEWPS  MOV 
ORA 
RAR 
ORA 
MOV 
RZ 
LDA 
SUB 
MOV 
MV  I 

XX SORT 1  MOV 

XX SORT 2  MOV 
ADD 
MOV 


% 

X  XRECL 

D,  O 

E,  A 

XXDMINUS 
D I RBUFP 
D 

D I RBUFP 
SFILES 
H,  A 

A,  H  ; START  NEW  PASS 

A  ; CLEAR  CARRY 

; CUT  IN  HALF 

A  ; SE  STATUS  FLAGS 

H, A  ; SAVE  NEW  VALUE 

; RETURN  WHEN  DONE 

SFILES 

H 

D,  A 
C,  1 

B, C 
A,  B 
H 

E, A 


;  SET  I  ?<  L  ADDRESS  POINTERS 


XXDISPI  PUSH 
MOV 
CALL 
SHLD 
POP 


H !  PUSH 
A,  B 

XX SET AD 
XXCRCEL 
B 1  POP 


XXDISPL 

PUSH 

H i  PUSH 

MOV 

A,E 

CALL 

XX SET AD 

SHLD 

XXCRCLl 

POP 

B !  POP  D 

XX COMP 

PUSH 

H !  PUSH 

LHLD 

XXCRCEL 

D !  PUSH  B 

D 1  POP  H 
D !  PUSH  B ! 

POP  H 

D !  PUSH  B 

(Continued  on  next  page) 
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DIR.ASM 


Listing 


(Listing  continued,  text  begins  on  page  34) 


XCHG 


LHLD 

XXCRCL1 

LDA 

XXRECL 

MOV 

B,  A 

CALL 

XXSCOMP 

POP 

B !  POP 

XX TEST 

ORA 

A 

JZ 

XXTEST1 

JM 

XXTEST1 

CALL 

XX SWAP 

MOV 

A,  B 

SUB 

H 

MOV 

B,  A 

JZ 

XXTEST1 

JC 

XXTEST1 

JMP 

XXSORT2 

XX TEST  1 

I  NR 

C 

MOV 

A,  D 

CMP 

C 

JC 

XXNEWPS 

JMP 

XXSORT1 

; COMPUTE  RECORD 

ADDRESS 

XXSETAD 

MV  I 

D,  0 

MOV 

E,A 

LDA 

XXRECL 

CALL 

XCHG 

XXMULT 

LHLD 

DIRBUFP 

DAD 

RET 

D 

;HL=E*A 

XX MULT 

LX  I 

H,0 

MV  I 

B,  8 

XXMULT1 

DAD 

RLC 

H 

JNC 

XXNOT1 

DAD 

D 

XXNOT1 

DCR 

B 

JNZ 

RET 

XXMULT 1 

XX SWAP 

PUSH 

H !  PUSH 

LDA 

XXRECL 

MOV 

B,  A 

LHLD 

XCHG 

XXCRCEL 

LHLD 

XXCRCL1 

XX SWAP 1 

LDAX 

D 

MOV 

C,  M 

MOV 

M,  A 

MOV 

A ,  C 

STAX 

D 

INX 

D 

I  NX 

H 

DCR 

B 

POP  H 

5  SET  THE  CPU  FLAGS 
; NO  NEED  TO  SWAP  ON  ZERO 
; . . .OR  MINUS. 


PUSH  B 

; RECORD  LENGTH 
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XX SWAP 1 
B !  POP 


; COMPARE  ALL  BITS  0-6,  SKIP  BIT  7 


XXSCOMP  DCR 
JM 
MOV 
AN  I 
MOV 
LDAX 
AN  I 
SUB 
INX 
INX 
JZ 

XXSC0M1  RET 


B 

XXSCOM1 
A,  M 
7FH 
C,  A 
D 

7FH 

C 

D 

H 

XXSCOMP 


;  MOVE 


BYTES  FROM 


— >  <DE) 


M0VH2D 


MOV 

STAX 

INX 

INX 

DCR 

JNZ 

RET 


A,  M 

D 

H 

D 

B 

M0VH2D 


; PUT  MESSAGE  POINTED  TO  BY  ’HL’  ON 
;’C’  IS  LENGTH  OF  MESSAGE 


SCREEN 


NPRINT 


-> 

EQU 

DCR 

RM 

MOV 

INX 

CALL 

JMP 


E,  M 
H 

PRINT 

NPRINT 


5  DISPLAY  THE  CHARACTER  PASSED  IN  ’E’  AND  MASK 
; WITH  BYTE  IN  ’MASK’.  (USED  HERE  TO  FORCE  LOWER 
; CASE  ON  FLAGGED  CHARACTERS) 

PRINT  PUSH  H!  PUSH  D!  PUSH  B!  PUSH  FSW 


LDA 
ORA 
AN  I 
MOV 
MV  I 
CALL 
POP 
RET 


MASK 

E 

7FH 
E,  A 

C , FCONOUT 
BDOS 

PSW !  POP 


(Continued  on  next  page) 
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DIR. ASM  Listing 


(Listing  continued,  text  begins  on  page  34) 


; STACK  SPACE 

DS  2  OH 

STACK  DW  0 


; DATA  STORAGE 

; SORTING  STORAGE 


XXNUL 

DB 

0 

XXCRCEL 

DW 

0 

XXCRCL1 

DW 

0 

XXRECL 

DB 

12 

; OTHER 

STORAGE 

BLS 

DW 

0 

DISK 

DB 

0 

; SAVE  CURRENT  DISK  HERE 

MASK 

DB 

0 

; UPPER/LOWER  CASE  MASK 

USERX 

DB 

0 

; ASSIGNED  USER  NUMBER 

USERC 

DB 

0 

; CURRENT  USER  NUMBER 

DIRBUFP 

DW 

o 

; DIRECTORY  POINTER 

BLM 

DW 

0 

; BLOCK  LENGTH  FROM  FUNCTI 

BSH 

DB 

0 

BISKSIZ 

DW 

0 

; MAX  DISK  SIZE 

MAXENT 

DW 

0 

; MAX  ENTRIES 

TSIZE 

DW 

0 

; SIZE  COUNTER 

TFILES 

DW 

o 

; ENTRY  COUNTER 

SFILES 

DW 

0 

; FILES  TO  SORT 

DUMMY 

DB 

*  9 

*  it  ■  :  9  -  9  -  9  -  9  -  9  - 

DS 

20 

; MESSAGES 

BADVER 

DB 

CR, 

LF,’ REQUIRES  CF/M  2’ , CR, LF, 7 

NOENT 

DB 

CR, 

LF ,  ’ NO  F I LE  * , CR , LF , ’ $ ? 

; SUMMARY  MESSAGE 
FOOTER  DB  CR, LF 

BB  ’  DRIVE  ’ 
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DRIVE 

USER 


DB  O 

DB  0,0, 0,0,0 

DB  ’ 

OB  ’  FILES:  ' 

FILES  DB  0,0,0,0,'0  <’ 

FREEF  DB  '  >  ’ 

DB 

DB  '  BYTES:  ’ 

BYTES  DB  0,0, 0,0, 'Ok  (' 

FREES  DB  '  k) 

DB  CR , LF , ’ * ’ 

OLDL  DB  QLDLEND— OLDL— 1 , '  ',7CH,'  ' 

OLDLEND  EBU  $ 

; TEMPROARY  SIZE  STORAGE 

KS I ZE  DB  O , O , O , O , O , ’ k  ' 

BUFFER  EQLI  $ 

End  Listing 
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DR.  DOBB’S  CLINIC 


by  D.  E.  Cortesi 


Diskette  Senility? 

Loren  Amelang,  of  Philo,  CA,  pre¬ 
sents  two  questions  of  considerable  inter¬ 
est.  Here  they  are. 

“1  seem  to  have  a  lot  of  trouble  with 
‘bad  sectors’  on  my  diskettes.  I  can  make 
a  backup  copy,  verify  it,  leave  it  on  the 
shelf  for  a  month,  and  come  back  to  find 
‘bad  sector’  errors.  If  I  recopy  a  diskette 
that  gives  read  errors,  it  will  be  fine  for  a 
month  or  two  and  then  fail  in  a  different 
spot.  What  happens  to  a  first-quality 
Dysan  or  Maxell  disk  that  makes  it  un¬ 
readable,  yet  leaves  no  permanent  dam¬ 
age? 

“Furthermore,  when  I  get  a  read  er¬ 
ror,  and  can’t  edit  or  dump  or  otherwise 
access  the  file  in  question,  1  can  always 
run  the  CRC  check  program  (from  the 
BDS  C  user  group)  and  it  can  access  the 
file  in  question!  How  can  it  be  that  one 
program  can  read  a  sector  that  another 
finds  hardware-level  (or  at  least  BIOS- 
level)  errors  in?” 

As  to  the  first  question,  we  once 
heard  that  the  mylar  of  which  the  disk  is 
made  can  pick  up  moisture  from  the  air. 
That  makes  it  swell  and  changes  its  radial 
dimensions,  maybe  just  enough  to  throw 
tracks  out  of  alignment.  That  might  be 
one  explanation  for  how  a  file  could  be¬ 
come  unreadable;  reformatting  such  a 
diskette  would  lay  down  new  tracks  that 
could  be  read.  But  we’ve  never  seen  any 
warnings  about  this  effect  in  print  — 
maybe  because  there  is  no  practical  way 
for  a  typical  user  to  control  it,  short  of 
installing  an  air-conditioned  computer 
room. 

However,  if  that  were  the  source  of 
Amelang’s  problem  it  ought  to  show  a  sea¬ 
sonal  variation,  with  failures  most  often 
at  the  start  of  California’s  rainy  season 
(and  again  at  the  beginning  of  summer?). 
It’s  a  pretty  flaky  theory,  now  that  we 
see  it  in  green  and  black.  Has  any  reader 
another  explanation?  Or  an  answer  to  the 
second  question  —  what  kind  of  I/O  is 
that  BDS  C  User  Group  utility  doing,  and 
how  can  the  rest  of  us  do  it? 

Computer  Catatonia? 

Ernest  Knipp,  of  Houston,  TX,  has 
seen  cases  where  some  unknown  cause, 
presumably  an  action  by  an  off-the-rails 
program,  has  hung  his  system  up  so  high 
that  he  has  had  to  power-down  and  -up 
again  to  get  it  going.  (Knipp’s  system  is 
not  an  IBM  PC,  which  can  be  put  in  that 
state  quite  easily  by  any  bug  that  clobbers 
either  the  8086  interrupt  vectors  or 
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MSDOS’s  chain  of  program-termination 
pointers.) 

“The  first  time  it  happened,”  Knipp 
writes,  “I  thought  something  internal 
must  be  bent,  broken,  or  burned  out.  It 
was  quite  a  while  before  I  caught  on  to 
the  power-down-and-up  maneuver.  Your 
suggestion  about  the  disk  [we  proposed 
that  the  disk  head  might  have  been 
stepped  back  outside  of  track  zero]  is 
interesting,  but  I  don’t  think  it  applies;  I 
have  a  front  panel  and  what  happens  is 
that  the  computer  never  moves  off  the  in¬ 
struction  at  location  zero,  so  it  never  has 
a  chance  to  do  anything  with  the  disk.  I 
have  been  guessing  it  was  in  some  kind  of 
wait  state  that  is  not  reset  by  a  front - 
panel  reset.” 

Okay,  readers  —  propose  ways  by 
which  a  (presumed  program)  bug  could 
put  a  Z80  system  into  permanent  cata¬ 
tonia  at  location  zero,  such  that  hitting 
the  reset  button  on  a  front  panel  would 
not  revive  it. 

Intern  Truncated 

Burks  Smith,  of  Shawnee  Mission, 
KS,  objects  to  our  comments  about 
floating-point  arithmetic  in  the  October 
issue.  Here  is  his  rebuttal. 

“You  say  that  complaints  that  inter¬ 
nal  binary  representation  is  more  prone 
to  truncation  errors  are  ‘misguided,’  but 
go  on  to  contradict  yourself  by  point¬ 
ing  out  two  very  good  reasons  not  to  use 
binary  representation.  They  are  that  any 
truncation  errors  in  decimal  arithmetic 
are  what  people  expect  them  to  be  with 
limited  precision,  and  that  some  frac¬ 
tions  that  have  a  finite  representation  in 
base  ten  do  not  have  a  finite  representa¬ 
tion  in  base  two.  In  fact,  the  decimal  frac¬ 
tion  1/10  can  not  be  represented  exactly 
as  a  binary  fraction,  no  matter  how  many 
bits  are  used,  and  this  would  seem  to  be 
reason  enough  to  favor  a  BCD  scheme  for 
internal  representation. 

“Your  admonition  to  never  use 
floating-point  arithmetic  in  ‘commercial’ 
calculations  and  suggestion  to  use  fixed- 
point  decimal  representations  available  in 
PL/I  and  COBOL  misses  the  point.  We 
were  talking  about  BASIC-80,  and  ex¬ 
cuse  me,  but  aren’t  high-level  languages 
supposed  to  be  for  the  convenience  of 
people  instead  of  CPUs?  If  something 
called  ‘double-precision  arithmetic’  can’t 
take  ten  percent  of  a  dollar  and  get 


exactly  ten  cents  there  shouldn’t  be  any 
excuses.  The  answer  is  just  plain  wrong!” 

Okay,  what  do  we  know?  Is  the  an¬ 
swer  just  plain  wrong?  Or  is  the  problem 
that  people  expect  mathematics  from  a 
CPU  that  is  only  capable  of  arithmetic  - 
and  only  approximate  arithmetic  at  that? 
In  what  senses  is  a  decimal  base  “better” 
than  a  binary  one?  Are  there  common  ra¬ 
tios  that  have  a  finite  representation  in  bi¬ 
nary  and  not  in  decimal?  The  BCD-based 
float. representation  used  in  CBASIC  has 
roughly  the  same  precision  as  the  double - 
precision  binary  representation  used 
in  MBASIC  and  BASCOM.  Has  anyone 
ever  benchmarked  the  two  methods  for 
(a)  commercial,  or  (b)  scientific,  compu¬ 
tations?  How  much  can  we  reasonably  ex¬ 
pect  of  computer  arithmetic  as  done  by 
current  languages?  What  ought  we  to  be 
demanding  of  the  implementors  of  the 
next  wave  of  compilers  and  interpreters? 
Is  there  a  numerical  analyst  in  the  house? 

Incidentally  the  choice  of  a  radix  for 
a  float  number  is  not  limited  to  binary 
versus  BCD.  There  are  hardware  systems 
that  operate  on  octal  and  hexadecimal 
digit-groups,  and  we  once  read  of  a  soft¬ 
ware  package  for  a  16 -bit  machine  that 
used  a  radix  of  10,000  -  each  “digit”  was 
a  16-bit  number  from  0  to  9,999. 

Finally,  if  anyone  wants  to  look  into 
these  matters  in  greater  depth,  here  are  a 
couple  of  sources.  Those  interested  in  the 
design  of  floating-point  arithmetic  meth¬ 
ods  might  start  with  Knuth's  Seminumeri- 
cal  Algorithms,  especially  section  4.2.2, 
“Accuracy  of  Floating-Point  Arithme¬ 
tic.”  For  the  user  of  a  system,  we  un¬ 
derstand  that  Richard  Hamming’s  Numer¬ 
ical  Methods  for  Scientists  and  Engineers 
is  considered  a  classic. 

Double  your  BASIC 

Aubrey  Hutchinson,  of  Pompano 
Beach,  FL,  has  sent  us  a  clutch  of  lovely 
sponses,  which  we  plan  to  dole  out  spar¬ 
ingly.  Here  is  the  first.  Were  you  aware 
that  the  built-in  editor  of  MBASIC  has 
the  ability  tc  duplicate  lines  of  code? 
It  isn’t  documented  anywhere  that  we 
know  of;  Hutchinson  found  it  by  acci¬ 
dent.  It  works  very  well,  at  least  on 
MBASIC  5.0. 

The  procedure  is  as  follows.  Suppose 
that  you  wan*  to  duplicate  line  10,  with 
the  duplicate  to  appear  as  line  320.  You 
give  the  command  LIST  10.  Immediately 
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after  the  line  appears,  enter  a  control-A. 
The  program  will  respond  with  the 
exclamation  mark  prompt.  Enter  an  “I” 
followed  by  the  target  line  number 
(“1320”  in  this  case)  and  press  return. 
The  new  line  320  will  be  displayed;  it  is 
a  duplicate  of  the  last  line  displayed  by 
LIST.  Hutchinson  notes  that  this  is  espe¬ 
cially  handy  when  you  want  to  make  an 
LPRINT  that  is  a  duplicate  of  some  earli¬ 
er  PRINT  statement.  We  played  around 
a  bit  and  think  that  there  may  be  more 
abilities  hiding  behind  this  control-A 
input. 

Etch-A-Vector 

In  the  December  DDJ  there  appeared 
an  article  by  Marek  W.  Michalski,  “A 
Simple  Vector  Generation  Algorithm.” 
Michalski  provided  a  flowchart  and  gave 
the  math  background  of  the  algorithm, 
but  didn’t  display  a  program.  We  couldn’t 
resist  the  challenge  of  making  a  program 


from  his  algorithm,  just  to  see  if  we  really 
understood  it.  The  only  graphics  machine 
handy  was  an  Atari  800,  so  we  wrote  the 
program  in  Atari  BASIC. 

It  turns  out  that  Michalski’s  algo¬ 
rithm  is  indeed  a  neat  one.  In  coding  it, 
the  challenge  comes  in  finding  a  way  to 
fold  the  eight  possible  cases  of  vector 
direction  into  as  few  code  routines  as  pos¬ 
sible.  The  eight  cases  arise  from  the  inter¬ 
action  of  three  factors.  The  X-direction 
may  be  positive  or  negative;  the  Y- 
direction  may  be  positive  or  negative; 
and  the  vector  may  be  longer  in  the  X- 
dimension  or  longer  in  the  Y-dimension. 
There  are  eight  combinations  of  those 
three  choices.  The  flowchart  given  in  the 
article  covered  only  one  case,  that  of  X 
positive,  Y  positive,  and  DX  greater  than 
(or  equal  to)  DY.  As  it  turned  out,  only 
two  routines  are  needed  to  handle  the 
eight  cases. 


The  program  (Listing  One,  this  page) 
runs  on  an  Atari,  but  doesn’t  have  much 
use  there  because  Atari  BASIC  already 
has  a  vector  statement  (DRAWTO).  But 
the  program  could  easily  be  converted  to 
another  BASIC;  only  the  Atari  verbs 
GRAPHICS,  COLOR,  and  PLOT  would 
have  to  be  changed.  More  to  the  point, 
the  algorithm  does  look  as  if  it  would  be 
very  fast  in  machine  language  (just  as 
Michalski  said).  Can  someone  use  it  that 
way?  Would  someone  like  to  put  it  into 
8086  code  for  the  IBM  PC? 

Our  recent  touching  pleas  for  input 
have  produced  some  good  letters.  Thanks 
to  all  who  wrote,  but  please  don’t  stop 
writing;  this  column  devours  material 
voraciously.  We  are  in  perpetual  need  of 
problems,  pitfalls,  puzzles  and  eurekas. 
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HARDWARE  REVIEW  - 

CP/M-80  Expansion  Card 
For  The  Victor  9000 


Product:  CP/M  Expansion  Card  for 

The  Victor  9000  and  IBM  PC 
Manufactured  by:  Small  Systems 

Engineering,  1056  Elwell  Court, 

Palo  Alto,  C A  94303 
Price:  $595  for  4  MHz  version 
$650  for  6  MHz  version 
Reviewed  by  Hank  Harrison 

Last  year  a  British  corporation  de¬ 
signed  a  board  dedicated  originally  to 
the  Victor  9000  version  released  in 
Europe  under  the  name  “Sirius  One.” 
This  little  board  is  a  bargain  and  is  the 
first  real  add-on  available  for  the  slowly 
but  surely  developing  Victor  9000  ma¬ 
chine -a  machine  which  now  comes 
supplied  with  10Mb  hard  disk  for  under 
$6,000. 

The  Board  is  a  Z-80  based  expansion 
board  designed  to  make  most  CP/M-80 
software  available  for  the  Victor- Sirius. 
It  is  also  available  for  the  IBM  PC  and  is 
similar  in  both  machines  except  that  the 
6MHz  model  costs  about  $55.00  more 
than  the  4MHz  version. 

Bear  in  mind  that  Chuck  Peddle’s 
Sirius  system  was  available  in  Europe  one 
full  year  prior  to  the  IBM  and  that  most 
European  designers  use  the  Sirius  as  a  stan¬ 
dard,  not  the  IBM.  Frankly,  the  Sirius  is, 
at  least  at  this  point,  twice  the  machine 
for  the  money  as  it  comes  out  of  the  box. 

I  am  difficult  to  impress,  but  this 
board,  one  of  the  few  expansions  availa¬ 
ble  for  the  Sirius-Victor  at  this  time,  is 
very  impressive  and  is  valuable  for  anyone 
developing  software  for  the  rugged  and 
well-designed  Victor  9000.  If  you  are  not 
developing  software  for  it,  and  are  among 
the  hordes  that  have  flocked  to  IBM,  I 
strongly  suggest  you  investigate  this 
classy  underdog. 

Price  and  function  are  the  two  main 
variables  I  look  for  in  a  piece  of  hardware. 
Next,  I  consider  reliability  and  ruggedness 
After  these  three  physical  parameters,  the 
real  proof  of  the  pudding  comes  to  play: 
I  am  interested  in  creativity  and  expres¬ 
sion,  not  mnemonic  frustration  or  diffi¬ 
culty  disguised  as  “challenge.”  I  will, 
therefore,  consider  any  board,  any  chip, 
any  piece  of  software  that  helps  me  get  to 
my  ultimate  goals  — absolute  transport¬ 
ability  and  absolute  transparency.  It  is 
obvious  that  Peddle  et  al.,  intend  to  hold 
their  market  loyalists  through  quality  and 
durability  and  although  not  totally  trans¬ 
parent,  the  Small  Systems  Engineering 
Z-80  board  is  a  definite  step  in  the  right 
direction. 


After  a  while  a  reviewer,  tech  writ¬ 
er  or  product  analyst  gets  a  good  feel  for 
what’s  good  and  what’s  slipshod.  Shoddy 
workmanship  is  very  obvious  in  any  com¬ 
puter  product,  overt  cosmetics  are  also 
obvious.  Sometimes  I  really  wonder 
where  the  design  engineers  went  to  school. 
I  wasn’t  aware  Dior  held  classes  in  hard¬ 
ware  these  days  but  perhaps  they  should. 

1  have  seen  all  manner  of  boards, 
tracings,  jumperings  and  reconfigurations 
over  the  past  seven  years.  IMSAI,  for  one, 
spent  minimal  time  in  R  and  D  and  docu¬ 
mentation,  almost  everything  went  into 
production  as  soon  as  possible.  The 
boards  just  went  out  into  the  field  and 
the  field  debugged  everything.  In  those 
days  people  were  happy  to  do  it  for 
Apple,  MITS  or  IMSAI  because  almost 
everybody  was  a  “freak.”  This  is  no  longer 
the  case  —  even  the  most  dedicated  com¬ 
puter  heavies  don’t  have  time  to  “mess 
about.” 

Esoteric  products  do  not  appeal  to 
the  New  Technology  user.  People  don’t 
really  want  to  modify  their  systems. 
Chuck  Peddle  knew  way  back  in  those 
Halcyon  days  at  Commodore  that  the  fu¬ 
ture  big  bucks  were  wrapped  up  in  an 
“out-of-the-box”  system.  The  Apple  lie 
is  following  suit. 

The  peripherals  business,  which  is 
where  the  big  money  is  now,  is  thriving 
because  the  out-of-the-box  system  is 


often  anemic,  incomplete  and  oblivious 
to  things  like  hooking  up  modems  and 
printers.  This  is  not  the  case  with  the 
Victor. 

Unlike  Americans  who  have  been 
overwhelmed  with  marketing  blab,  Euro¬ 
peans,  who  see  very  few  ads  on  television 
(and  are  therefore  deprived  of  Charlie 
Chaplin’s  antics  in  the  bakery),  prefer 
quality  and  completeness  out  of  the  box. 
Europeans  tend  to  be  penny  pinchers 
who  demand  portability  of  their  old  Soft¬ 
ware  and  it  was  to  meet  this  need  that  the 
Small  Systems  Z-80  card  was  born. 

The  Small  Systems  Z-80  card  is  a 
multi-function  wondercard.  It  plugs  in 
and  that’s  it.  Installation  in  my  system 
took  twenty  minutes,  five  of  those  min¬ 
utes  were  spent  cleaning  the  screen  since  I 
had  the  monitor  off  anyway. 

The  card  fits  any  of  the  four  Victor 
9000  expansion  slots.  We  selected  num¬ 
ber  one  as  it  is  closest  to  the  venting 
holes. 

The  card  must  be  fitted  with  the  chips 
away  from  the  disk  drives,  but  there  are 
no  red  arrows  printed  on  the  card.  There 
is  also  no  way  to  cement  this  in  place  and 
the  bus  structure  is  almost  like  an  S-100 
system  with  no  top  clips  or  slot  guides.  I 
strongly  urge  Victor  Systems  to  build  a 
$12.00  add-on  cage  frame  or  Small  Sys¬ 
tems  to  provide  clips. 


Small  Systems  Engineering  expansion  card  for  Victor  9000  adds  64K  RAM, 
hard  disk,  virtual  disk,  and  BSTAM  capabilities. 
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I  feel  very  weak-willed  in  moving  a 
computer  from  room  to  room  when  the 
boards  are  rattling  in  the  slot.  I  have  in¬ 
vested  more  than  $1,500.00  in  custom 
“suitcases”  for  my  system.  The  Victor  is 
very  portable  in  this  fashion  and  weighs 
about  as  much  as  two  Osbornes  or  one 
KayPro  II  and  a  printer,  but  no  amount 
of  outside  protection  can  compensate  for 
a  kludgy  bus  connection. 

Once  in  place,  the  board  achieves 
some  small  miracles: 

1 )  It  gives  64K  of  extra  RAM  and  boots 
as  a  separate  computer. 

2)  It  boots  CP/M-80  programs. 

3)  It  connects  to  Corvus  or  Corvus-like 
5,10  and  20  Mb  hard  disk  units. 

4)  It  makes  possible  BSTAM,  or  “move 
it,”  communications. 

5)  It  utilizes  Corvus  networking  or  any 
networking  conforming  to  Corvus 
protocols. 

6)  It  supports  diagnostics,  e.g.,  Memtest, 
DDT,  etc. 

7)  It  allows  for  Corvus  Mirror  back-up, 
although  floppy  front-up,  if  done 
properly,  is  all  that  is  needed. 

8)  It  provides  an  “M”  option  which  is  a 
virtual  disk  that  can  be  written  to 
and  which  can  act  as  an  executive’ 
For  the  most  part  the  ability  to  run 

more  than  2000  old  programs  still  good 
enough  to  use  on  a  hot  new  16-bit  sys¬ 
tem,  makes  the  board  worth  the  price, 
but  this  board  also  takes  advantage  of  the 
large  amount  of  RAM  available  in  my  sys¬ 
tem,  presently  256Kb  plus  the  64K  on 
the  8-hit  Z-80  card. 

Imagine  the  contradiction  in  terms:  a 
CP/M-80  file  in  excess  of  20K  safely 
loaded  into  RAM  and  processed  by  Word¬ 
Star  with  no  disk  access  after  boot.  In 
fact,  my  book  chapters  are  typically  90K. 
Using  the  Small  Systems  card,  I  was  able 
to  use  a  footnote,  a  Thesarus,  and  a  global 
search  and  replace,  in  both  directions 
with  no  penalty  and  with  amazing  speed. 

I  also  booted  a  German  data  base  called 
Aladdin  and  my  own  proprietary  spelling 
checker  called  Zero  Glich.  I  experienced 
no  “DELETING  CURRENT  BACK  UP 
TO  MAKE  ROOM  FOR  SAVE”  error 
messages. 

We  will  be  continuing  to  review  the 
Victor  developments.  Unfortunately,  we 
just  didn’t  have  time  to  compare  the  Small 
Systems  Z-80  board  in  both  intended 
hosts  at  this  time.  I  personally  would  love 
to  do  a  straight  head-to-toe  face-off 
comparison  between  IBM  and  Victor,  but 
many  factors  mitigate  against  this. 

In  short,  the  Small  Systems  Z-80 
board  opens  up  an  entire  range  of  micro 
capabilities  from  8-bit  to  potential  16-bit 
systems  and  makes  the  Victor  9000  quite 
attractive,  especially  in  view  of  Chuck 
Peddle’s  recent  fait  accompli  wherein  the 


entire  operation  is  coming  back  home 
from  Chicago.  Peddle  wants  to  locate  the 
French  headquarters  in  Nice. 

The  following  information  represents 
an  update  on  the  Sirius-80  card,  and  on 
applications  not  currently  covered  in  the 
User’s  Manual. 

Hard  Disk 

There  are  now  two  ways  to  operate  a 
hard  disk  on  the  Sirius-Victor  using  the 
Z-80  card.  First,  under  CP/M-80  which 
runs  on  the  card’s  Z80  processor  and  can 
access  the  card’s  built-in  Corvus  hard  disk 
port  or  alternatively  under  CP/M-86 
which  runs  on  the  Sirius  main  processor 
(8088)  and  uses  the  Sirius-80  card  as  a 
hard  disk  interface. 

The  hard  disk  interface  on  the  Sirius- 
80  card  will  drive  a  Corvus  5,  10  or  20 
megabyte  hard  disk  but  others  may  soon 
be  plug  compatible.  CP/M  operation 
using  a  hard  disk  is  similar  to  operation 
using  floppy  disks,  but  is  much  faster  and 
offers  more  on-line  storage  capacity. 

Drive  Access  Time: 

10  or  20  Mbyte  drive:  80ms  maximum 
40ms  average 

5  Mbyte  drive:  240ms  maximum 

125ms  average 

Normally  drive  A  will  be  the  handle 
hung  on  the  disk  drive,  because  it  will  be 
used  most.  As  CP/M  version  2.2  normally 
only  supports  drives  up  to  8  Megabytes. 
The  drive  is  divided  into  two  or  four  logi¬ 
cal  CP/M  drives.  These  will  typically  then 
be: 

5  or  10  Megabyte  drive  — 

CP/M  drives  A:  and  B: 

20  Megabyte  drive  — 

CP/M  drives  A:,  B:,  C:  and  D: 

“Drive  M”  is  an  additional  feature 
which  is  built  into  the  latest  release  of  the 
Victor-80  card  software.  It  allows  use  of 
any  additional  RAM  cards  in  the  system 
by  treating  them  as  a  CP/M  pseudo  disk 
drive,  called  drive  M.  This  enables  the 
loading  of  all  frequently  used  files  and 
programs  into  RAM  at  the  start  of  a  ses¬ 
sion  (by  PIPing  them  across  onto  drive  M) 
for  faster  execution. 

The  RAM  card  behaves  as  a  high¬ 
speed,  volatile  (but  otherwise  normal) 
CP/M  disk  drive,  and  all  the  normal  com¬ 
mands  such  as  STAT,  PIP,  ERA  and  DIR 
will  work  on  it. 


“Drive  M”  Operation 
Under  CP/M-80 

The  System  Disk  is  supplied  with  a 
file  called  NEWSYS.  Typing  in  HEWSYS 
and  a  carriage  return  brings  it  up.  The 
NEWSYS  program  will  ask: 


Reconfigure  “80.CMD”  on  which 
drive  (A-P)? 

Reply  to  this  question  with: 

A 

followed  by  a  carriage  return. 

When  the  system  to  be  reconfigured 
has  been  loaded  into  memory,  NEWSYS 
will  display  a  menu  of  options: 

A  —  autoload  command 

D  —  disk  drive  assignments 

P  —  change  I/O  port  number 

E  —  execute  reconfigured  system 

S  —  save  reconfigured  system 

Q  —  quit  to  CP/M 

Typing  “D”  followed  by  a  carriage 
return,  you  now  have  seven  choices  of  disk 
drive  assignments  as  shown  in  Figure  1 . 

The  drive  M  parameters  for  CP/M-80 
can  be  changed  by  using  the  command  in 
the  NEWSYS  program.  The  first  parameter 
is  the  base  starting  paragraph  of  the  mem¬ 
ory  to  be  used  by  drive  M  (i.e.,  the  hex 
starting  address  divided  by  16).  This  de¬ 
faults  to  2C0  hex,  the  first  memory  para¬ 
graph  not  normally  used  for  screen  han¬ 
dling.  The  default  may  be  altered  if  special 
screen  handling  routines  are  used  or  if 
drive  M  is  to  be  used  with  a  RAM  card 
which  is  not  contiguous  with  the  normal 
system  memory  (e.g.,  to  maintain  compat¬ 
ibility  with  drive  M  as  used  under  CP/M- 
86). 

The  second  parameter  is  the  memory 
size  (number  of  Kilobytes,  in  decimal)  to 
be  used  by  drive  M.  This  would  normally 
be  set  to  the  size  of  the  memory  card,  or 
zero  (to  automatically  use  all  the  memory 
available  up  to  the  base  of  the  operating 
system  software). 

The  final  parameter  specifies  whether 
the  drive  M  directory  is  to  be  cleared  on 
entry  to  CP/M-80.  This  would  normally 
default  to  YES  unless  it  is  desired  to  ac¬ 
cess  the  same  memory  card  from  both 
CP/M-80  and  CP/M-86.  In  this  case,  the 
directory  will  be  cleared  once  and  for  all 
when  CP/M-86  is  booted,  and  all  files 
will  be  preserved  and  can  be  accessed 
under  both  CP/M-80  and  CP/M-86  until 
the  system  is  powered  down  or  reset. 

If  the  question,  “Do  you  wish  to  use 
the  ‘Drive  M’  RAM  card  facility  (Y/N)?” 
is  answered  with  a  “Y”,  HARD86  will  ask 
for  the  start  address  and  size  of  the  RAM 
card.  The  start  address  should  be  a  hexa¬ 
decimal  paragraph  address  (1  paragraph  = 
16  bytes),  and  the  size  should  be  the  de¬ 
cimal  number  of  Kilobytes  (multiples  of 
1024  bytes)  so  that  if  the  RAM  cards  (or 
card)  occupy  physical  addresses  80000 
to  BFFFF  hex,  enter  “8000”  for  the  start 
address  and  “256”  for  the  size. 

Memory  blocks  can  be  addressed 
anywhere  in  the  range  20000  to  DFFFF 
hex  but  memory  cards  should  be  discon¬ 
tinuous  with  the  main  system  memory 
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(at  00000  to  1FFFF  hex).  This  tidiness 
prevents  CP/M-86  from  relocating  itself 
into  free  memory. 

Remember,  any  files  stored  on  drive 
M  will  be  lost  on  cold  boot  and  files  on 
drive  M  will  be  preserved  during  opera¬ 
tion  under  CP/M-80. 

Note  also  that  CP/M  was  never  origi¬ 
nally  designed  to  operate  in  a  multi-user 
environment.  MP/M  was  designed  to  sup¬ 
port  more  than  one  user  on  the  same  pro¬ 
cessor,  but  this  involves  sharing  of  the 
central  processor  and  memory  as  well  as  a 
disk  drive.  The  Victor-80  card  remains  a 
single  user  system  enhancement  and  is 
not  a  co -processing  card,  but  allows  net¬ 
working  through  a  constellation  box. 


Input/Output  Addressing 

The  Victor-80  card  occupies  one  of 
the  65,536  available  Victor  I/O  port  ad¬ 
dresses.  It  is  normally  shipped  to  work 
with  I/O  port  0,  but  this  may  need  to  be 
changed  if  it  conflicts  with  other  expan¬ 
sion  cards  in  view  of  the  fact  that  a  full 
Megabyte  of  RAM  is  now  available. 

To  change  the  port  address,  you  will 
need  to  alter  the  switches  on  the  Victor- 
80  card  and  change  the  port  address  in 
the  CP/M-80  or  CP/M-86  system  soft¬ 
ware  (using  a  NEWSYS  or  HARD86  pro¬ 
gram  respectively). 

The  following  switch  assignments  de¬ 
fault  to  OFF  and  refer  to  the  two  on¬ 
board  Dual  In-line  Packages.  The  listing 
implies  ON  is  selected. 

Switch  1  (nearest  center  of  card) 

1  -  I/O  address  bit  0 

2  —  I/O  address  bit  1 

3  —  I/O  address  bit  2 

4  —  I/O  address  bit  3 

5  —  I/O  address  bit  4 

6  -  I/O  address  bit  5 

7  —  I/O  address  bit  6 

8  —  I/O  address  bit  7 

9  -  I/O  address  bit  8 
10  -  I/O  address  bit  9 

Switch  2  (furthest  from  center  of  card) 

1  —  I/O  address  bit  10 

2  —  I/O  address  bit  1 1 

3  -  I/O  address  bit  1  2 

4  —  I/O  address  bit  13 

5  —  I/O  address  bit  14 

6  —  I/O  address  bit  1 5 

7  —  Reserved  for  future  use 

8  —  Reserved  for  future  use 

9  —  Reserved  for  future  use 
10  —  Reserved  for  future  use 

7  and  8  should  be  left  unaltered. 

The  Z-80  card  address  map  appears 
as  shown  in  Figure  2. 


Some  Notes  on 

Serial  Communications 

—  BSTAM  using  Serial  Port  “B” 

A  version  of  the  BSTAM  driver  has 
been  produced  to  use  serial  port  B  on  the 
Victor  9000.  This  allows  serial  port  A  to 
be  reserved  exclusively  for  use  with  a 
serial  printer  (the  TTY :  device),  the  paral¬ 
lel  port  is  usually  designated  for  a  daisy 
wheel,  the  serial  for  dot  matrix,  but  a 
switching  set-up  on  the  parallel  port  is 
highly  recommended  for  multi-printer 
installations. 

The  new  driver  is  in  a  file  called 
USIRIUSB.ASM  on  the  Victor-80  disk. 
It  should  be  assembled  and  patched  into 
your  copy  of  BSTAM  described  in  the 
User’s  Manual,  Appendix  A. 

Note  that  both  the  “ port  A  ”  and 
“port  B”  BSTAM  drivers  automatically 
pre-set  the  appropriate  port  to  9600  baud. 
If  the  machine  being  communicated  with 
will  not  work  at  9600  baud,  you  will 
need  to  modify  the  Victor-80  BSTAM 
drivers  to  set  up  a  different  baud  rate. 

The  Victor  9000  serial  port  is  wired 
to  appear  as  a  terminal  for  use  with  mo¬ 
dems  and  for  local,  double  twist  wire  net¬ 
working.  Thus  pin  2,  instead  of  the  more 
usual  pin  3,  is  used  for  handshaking.  This 
means  that  when  using  BSTAM  to  con¬ 
nect  the  Victor  to  another  machine,  pins 
2  and  3  should  not  be  crossed  over  in  the 
connecting  cable  as  they  normally  are  in 
the  RS232  tradition.  The  cable  connec¬ 
tions  should  be: 

Computer  Remote  computer 

pin  2  (data  out)  ■»  pin  2  (data  in) 
pin  3  (data  in)  ♦  pin  3  (data  out) 
pin 7 (signal  ground)  *  pin7(signal  ground) 

It  is  important  to  ensure  that  the 
copy  of  BSTAM  on  the  remote  computer 
has  been  correctly  configured  for  that 
machine,  and  that  the  remote  machine 
has  been  set  up  for  the  correct  baud  rate 
(i.e.,  9600),  one  stop  bit,  eight  data  bits, 
and  no  parity. 


Setting  Up  Port  A  for  a 
9600  Baud  Serial  Printer 

The  program  “9600.CMD”  on  the 
Small  Systems  Z-80  diskette  is  provided 
to  set  the  CP/M  list  device  to  be  TTY: 
(serial  port  “A”),  and  at  the  same  time, 
set  its  baud  rate  to  9600.  This  program  is 
necessary  because  the  baud  rate  setting 
program  provided  by  Victor  has  a  current 
maximum  of  4800  baud. 


In  the  final  analysis,  things  are  brew¬ 
ing  at  Victor,  that  small  think-tank  up  in 
Scotts  Valley  just  beyond  the  Silicon 
smog  margin.  And  sales  at  Small  Systems 
Engineering  should  heat  up  rather  quickly. 
It  is  hoped  that  multi-purpose  boards  like 
this  will  be  available  for  all  computers  so 
we  can  all  move  anywhere  we  want. 
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SOFTWARE  REVIEW 

REVAS  Disassembler 


Product:  REVAS  Version  3.0 
Company:  REVASCO,  6032  Chariton 

Avenue,  Los  Angeles,  California 

(213)649-3575 
Computer:  Z80  CPU  with  CP/M 
Format:  8”  SSSD,  SSSD  Northstar, 

Microplis  Mod  II 
Minimum  Memory:  32K 
Release  Date:  January  1982 
Price:  $90.00 

Reviewed  by  Steve  Willoughby 

This  disassembler  produces  console, 
printer,  and  .ASM  and  .PRN  type  files 
from  8080  or  Z80  machine  code  which  is 
memory  resident  or  disk  resident  in  .COM 
type  files  up  to  64K  bytes  in  length. 

The  disassembler  will  disassemble  the 
undocumented  Z80  opcodes  in  addition 
to  standard  opcodes.  Output  mnemonics 
are  in  TDL  or  Z1LOG  format  and  are  se¬ 
lected  by  running  the  particular  variation 
of  REVAS  (both  included). 

The  disassembler  provides  locking  of 
specified  memory  areas  for  disassembly  as 
BYTE  or  word  data.  Provision  is  also 
made  for  multiple  inclusion  of  a  comment 
line  in  the  output  as  a  particular  location 
is  disassembled. 

The  disassembler  includes  search  and 
cross  reference  functions,  display  of  inter¬ 
nal  and  user  parameters,  and  a  calculator 
mode.  Numbers  can  be  input  and  output 
in  any  radix  with  independent  input  and 
output  radices.  Provision  is  made  for  user 
parameters  to  allow  customization  of 
print  output  with  many  popular  printers. 

BACKGROUND 

A  disassembler  reverses  the  process 
in  which  an  assembler  converts  mnemonic 
codes  and  symbolic  values  into  machine 
language.  A  disassembler,  therefore,  at¬ 
tempts  to  reconstitute  the  mnemonic 
code  from  the  machine  code.  The  dis¬ 
assembler  is  used  to  maintain  or  modify 
machine  code  for  which  the  sources  are 
not  available,  and  as  a  debugging  tool. 
Those  who  have  used  DDT  have  exper¬ 
ienced  a  limited  disassembler. 

Several  problems  prevent  the  dis¬ 
assembler  from  performing  the  ideal 
translation  of  the  machine  code  into  the 
original  source  code.  The  original  assembly 
removed  the  source  comments  and  con¬ 
verted  the  symbolic  arguments  into  abso¬ 
lute  binary  numbers;  in  addition,  the 
disassembler  cannot  distinguish  embedded 


data  and  instructions.  A  good  disassembler 
allows  the  human  to  interact  and  remedy 
these  problems.  The  human  can  disassem¬ 
ble  an  area  of  code  looking  for  meaning¬ 
less  instruction  sequences  or  blocks  of 
data  which  have  ASCII  values  reading  as 
text.  These  areas  can  then  be  flagged  as 
embedded  data  and  will  be  subsequently 
decoded  as  data,  not  instructions.  A  good 
disassembler  will  generate  synthetic  labels 
wherever  a  number  would  have  been  gen¬ 
erated  from  a  symbolic  argument. 

An  outstanding  disassembler  builds  a 
symbol  table  of  these  synthetic  labels  and 
allows  the  human  to  redefine  the  label  to 
one  which  is  meaningful  (or  the  original 
symbolic  label).  Further  disassemblies  will 
replace  the  number  with  the  label  from 
the  symbol  table.  This  provides  disassem¬ 
bly  listings  that  look  very  much  like  the 
original  source  code.  An  outstanding  dis¬ 
assembler  allows  comments  to  be  added 
to  the  output.  While  size  and  memory 
usage  constrain  the  degree  of  comments 
available,  at  least  there  should  be  provision 
for  inserting  a  line  of  comments  at  key 
places  in  the  disassembly  to  document 
program  sections  or  subroutines. 

A  good  disassembler  will  disassemble 
memory  resident  code  and  produce  a 
printed  output.  An  outstanding  disassem¬ 
bler  accepts  disk  file  input  and  output  in 
addition,  allowing  a  very  large  program 
to  be  disassembled  and  producing  output 
on  a  medium  ready  for  re-assembly. 

A  good  disassembler  allows  aids  for 
the  human  to  calculate  binary  add  and 
subtract  in  one  radix  (usually  octal  or 
hexadecimal).  An  outstanding  disassem¬ 
bler  provides  for  dynamic  specification 
of  radix  and  also  provides  multiplication, 
division,  and  modulo  calculation. 

The  general  usage  of  a  disassembler 
follows  this  scenario:  User  has  machine 
code  program  for  which  vendor  won’t 
release  source  code  and  which  has  some 
bug  or  feature  preventing  operation  on 
user’s  system;  or  software  won’t  work 
with  user’s  particular  peripherals;  or  the 
user  has  printed  source  listing  but  no 
computer  readable  form  of  sources.  User 
first  uses  disassembler  to  generate  prelimi¬ 
nary  source  file.  User  then  uses  editor  to 
make  changes,  add  comments,  etc.  User 
finally  assembles  source  file  to  generate 
new  machine  code  program  curing  prob¬ 
lem  or  proceeds  with  edit -assembly -try 
iteration  until  problem  is  solved. 


REVIEW 

As  one  may  gather  from  the  previous 
discussion  of  symbolic  labels,  data  and 
comments,  one  does  not  just  dash  off  a 
disassembly,  even  with  an  excellent  dis¬ 
assembler.  The  capability  of  the  disassem¬ 
bler,  however,  will  affect  the  time  required 
to  get  the  desired  results  and  the  sophisti¬ 
cation  of  the  results  (you  get  what  you 
pay  for). 

I’ve  used  the  REVAS  Version  3.0  dis¬ 
assembler  and  consider  it  outstanding  in 
all  respects.  REVAS  is  very  complex  be¬ 
cause  of  its  many  features  to  help  the 
human  decipher  the  machine  code;  how¬ 
ever,  the  manual  has  a  guided  tour  through 
a  disassembly  of  a  supplied  disk  file  that 
quickly  and  effortlessly  acquaints  the 
new  user  with  REVAS  to  the  point  of 
self-sufficiency.  I  appreciated  the  calcu¬ 
lator  mode’s  ease  of  converting  disk  block 
numbers  to  sector  and  track  using  the  di¬ 
vide  and  modulo  fuctions.  1  used  REVAS 
on  a  CP/M  1.4  system  so  REVAS  should 
also  work  for  those  who  are  running 
CDOS. 

The  manual  is  near  perfect.  In  fact, 
I  found  only  two  errors  in  the  manual. 
The  manual  was  well -organized  and  well- 
polished,  evidencing  its  preparation  on  a 
word  processor  with  a  daisy -wheel 
printer. 

My  two  complaints  are  that  the 
copying  is  uneven,  showing  it  was  not 
typeset,  and  that  the  general  tone  of  the 
introductory  chapters  seems  to  talk  down 
to  the  reader  making  reading  tedious.  My 
overall  impression  is  that  of  a  very  mature 
product. 

My  resistance  threshold  on  software 
of  this  type  is  $50,  but  I  will  make  an 
exception  for  REVAS.  It  is  definitely 
worth  its  $90  pricetag  to  someone  who 
needs  more  than  the  disassembly  capa¬ 
bility  of  DDT  or  DEBUG.  My  next  project 
is  to  convert  a  cassette  BASIC  to  run 
under  CP/M.  This  is  the  sort  of  project 
for  which  REVAS  is  ideal. 

Performance:  Excellent 
Documentation:  Superior 
Price:  Good 
Value:  Excellent 
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BOOK  REVIEWS 


Data  Communication  for  Microcomputers 
By  Nichols,  Nichols,  and  Musson 
Published  by  McGraw-Hill 
$ 1 6.95 

also 

TRS-80  Data  Communications  Systems 
By  Frank  Derfler,  Jr. 

Published  by  Prentice-Hall 
SI  2.95 

Reviewed  by  Joseph  B.  Rothstein 

The  computer  has  been  called  “the 
general  purpose  tool,”  and  one  of  the 
most  important  questions  any  computer 
designer  or  computer  user  must  answer  is 
“What  does  a  general  purpose  tool  look 
like?”. 

One  answer  to  that  question,  which 
was  not  anticipated  by  the  first  computer 
engineers,  is  that  the  modern  computer 
often  looks  like  a  telephone.  Numerous 
computer-based  products  exist  solely  for 
the  purpose  of  communicating  over  tele¬ 
phone  lines,  while  an  equal  number  of 
products  serve  as  add-ons  to  conventional 
computers,  enabling  them  to  tap  into  the 
growing  number  of  databases,  information 
utilities,  and  other  users  accessible  through 
the  worldwide  telephone  network. 

But  the  microcomputer  user  anxious 
to  enter  this  brave  new  world  is  confronted 
by  a  bewildering  array  of  buzzwords  and 
options.  Having  only  begun  to  master  the 
jargon  associated  with  microcomputers, 
the  neophyte  may  be  reluctant  to  face 
yet  another  learning  curve,  characterized 
by  such  terms  as  “physical  layer  protocol,” 
“star  topology,”  and  “collision  handling.” 

Two  recent  books  with  similar  titles 
attempt  to  address  this  dilemma,  each  in 
a  different  fashion.  Data  Communication 
for  Microcomputers ,  by  Elizabeth  A. 
Nichols,  Joseph  C.  Nichols,  and  Keith  B. 
Musson,  offers  a  wide-ranging  discussion 
of  data  communication  principles  and 
hardware,  without  focusing  on  a  particu¬ 
lar  computer.  The  authors  are  consultants 
in  the  data  communications  field,  and 
their  text  might  be  more  appropriate  for 
the  curious  user  of  a  large-scale  telecom¬ 
munications  system  than  for  the  first-time 
microcomputer  owner  who  only  wants  to 
know  how  to  dial  up  one  of  the  consumer- 
oriented  information  utilities. 

TRS-80  Data  Communications  Sys¬ 
tems ,  by  Frank  Derfler,  Jr.,  focuses  in¬ 
stead  on  a  much  narrower  topic  —  the 
implementation  and  use  of  telecommuni¬ 
cations  systems  for  Radio  Shack’s  popular 
microcomputer. 


Both  texts  address  the  essential  ques¬ 
tion,  “What  is  data  communications,  and 
how  can  1  make  use  of  it  on  my  micro¬ 
computer?”.  But  beyond  that,  they  are 
hardly  equivalent  treatments  of  the  same 
subject. 

The  Nicholses  and  Musson  approach 
the  subject  from  three  perspectives.  Their 
intention  is  to  offer  practical  information 
on  such  topics  as  how  to  fabricate  a  cable 
or  choose  a  modem,  while  at  the  same 
time  providing  a  tutorial  on  the  concepts 
and  principles  of  data  communications 
and  also  serving  as  a  reference  tool.  They 
are  partially  successful  in  meeting  each  of 
these  goals,  but  despite  the  text’s  264 
pages  and  hefty  price  tag,  I  was  not  fully 
satisfied  with  their  handling  of  any  one  of 
their  three  areas  of  concern. 

The  hardware  hacker,  who  appreciates 
workshop  tinkering  for  its  own  sake,  may 
find  the  most  to  enjoy.  The  authors  have 
included  a  series  of  experiments  for  the 
reader  to  perform,  ranging  in  complexity 
from  fabricating  a  three-wire  economy 
model  RS-232-C  cable,  to  implementing 
interrupt-driven  I/O  on  an  S-100  or  TRS- 
80  computer.  Though  the  experiments 
are  thoroughly  described,  including  lists 
of  required  materials  and  equipment,  as 
well  as  software  listings,  the  relationship 
of  the  experiments  to  real-world  data 
communications  tasks  is  not  clearly 
established.  Several  of  the  experiments 
involved  fabricating  different  kinds  of 
cables,  for  example,  yet  the  related  text 
does  not  adequately  make  clear  how  the 
user  is  to  know  what  sort  of  cable  is 
required  for  a  particular  situation. 

Novices  to  data  communications  may 
find  themselves  overwhelmed  by  the  tu¬ 
torial  on  the  subject,  for  it  includes  far 
more  than  most  microcomputer  owners 
would  find  necessary  in  order  to  join  the 
ranks  of  computer  communicators.  While 
there’s  surely  nothing  wrong  with  offering 
more  information  than  required,  many 
readers  may  become  impatient  with  an 
approach  that  does  not  get  around  to 
covering  modems  until  page  221. 

Though  there’s  no  lack  of  informa¬ 
tion  in  Data  Communication  for  Micro¬ 
computers,  it  falls  short  of  being  an  im¬ 
portant  reference  on  the  subject.  There 
are  no  appendices,  quick  reference  guides, 
or  comprehensive  tables,  so  random  access 
to  a  particular  topic  is  limited  to  the  table 
of  contents  and  the  index.  Telecommuni¬ 
cations  managers  would  probably  not 
want  to  rely  on  Data  Communication  for 
Microcomputers,  but  it  might  be  useful  to 


a  business  person  trying  to  cope  with  the 
jargon  used  by  data  communications 
salespeople. 

Perhaps  the  authors  would  have  been 
more  successful  in  their  intentions  if  they 
had  actually  written  three  volumes,  in¬ 
stead  of  trying  to  satisfy  three  audiences 
in  a  single  text.  By  trying  to  be  all  things 
to  all  types  of  readers,  they  have  limited 
their  usefulness  to  each. 

This  is  not  a  problem  for  Frank 
Derfler,  Jr.  He  has  the  audience  of  TRS- 
80  Data  Communications  Systems  firmly 
in  mind  on  each  of  the  159  pages,  and 
goes  right  to  the  heart  of  the  subject.  The 
role  and  fundamental  principles  of  data 
communications  are  covered  in  the  first 
twenty-one  pages,  while  the  bulk  of  the 
remaining  text  is  devoted  to  the  imple¬ 
mentation  and  use  of  the  TRS-80  as  a 
data  communications  instrument.  Begin¬ 
ning  with  a  discussion  of  the  TRS-80 
serial  port,  Derfler  covers  such  topics  as 
modems,  terminals,  accessing  microcom¬ 
puter-based  message  systems,  and  tele¬ 
communications  for  the  deaf. 

Of  course,  much  of  the  text  is  of 
limited  value  to  owners  of  other  brands 
of  microcomputers,  but  that  is  to  be 
expected.  The  emphasis  here  is  on  the 
practical  needs  of  the  TRS-80  user,  and 
this  audience  is  well  served.  The  author’s 
approach  is  measured  and  thorough, 
though  not  at  all  dry  or  technical.  Prac¬ 
tical  considerations  are  emphasized  in  dis¬ 
cussing  such  subjects  as  the  difference 
between  “originate”  and  “answer”  mode, 
or  how  to  determine  which  signal  goes  on 
which  wire  of  a  cable. 

The  text  includes  descriptions  of  spe¬ 
cific  products  available  for  the  TRS-80, 
and  an  appendix  contains  the  names  and 
addresses  of  more  than  20  manufacturers 
and  distributors  of  data  communication 
products.  Similarly,  the  author  mentions 
several  information  utilities  and  micro- 
computer-based  message  systems  of  po¬ 
tential  interest  to  TRS-80  users.  And 
unlike  the  Nichols/ Musson  text,  there 
is  a  brief  glossary  of  important  terms. 

Frank  Derfler,  Jr.  writes  frequently 
on  data  communications  topics  for  the 
microcomputer  popular  press,  and  he  uses 
the  breezy,  conversational  style  of  those 
publications  in  his  book  as  well.  His  ob¬ 
servations  on  such  topics  as  the  current 
information  network,  scenarios  of  the 
future,  and  social  analysis  contribute  to 
the  readability  of  TRS-80  Data  Commu¬ 
nications  Systems,  and  provide  food  for 
thought  which  serves  to  complement  the 
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“how-to”  aspects  of  the  text. 

The  TRS-80  user  who  wants  to  cross 
the  frontier  of  data  communications 
would  likely  have  a  long  wait  for  a  more 
valuable  text  than  TRS-80  Data  Commu¬ 
nications  Sytems.  Others,  using  different 
gear,  may  find  Data  Communication  for 
Microcomputers  worth  considering  as  an 
interim  step,  until  something  more  appro¬ 
priate  and  useful  comes  along. 

The  Network  Revolution: 

Confessions  of  a  Computer  Scientist 

By  Jacque  Vallee 

Published  by  AND/OR  Press,  Inc., 

Berkeley,  California 
$7.95 

Reviewed  by  Virginia  Lyons 

For  those  readers  who  enjoy  socio¬ 
logical  and  philosophical  speculations  on 
computer  systems,  Jacques  Vallee  has  just 
published  his  new  book,  The  Network 
Revolution:  Confessions  of  a  Computer 
Scientist.  In  it  Vallee  outlines  just  how 
communications  are  changing  the  funda¬ 
mental  structure  of  modern  society. 

Until  the  development  of  the  person¬ 
al  computer,  mass  communications  were 
centralized,  one-way,  non-adaptive  mes¬ 
sages  distributed  to  a  captive  audience. 
Television,  telephone,  radio  and  print 
media  are  advertising  and  marketing  in¬ 
dustries  in  which  the  mass  audience  is  the 
product  sold  to  the  advertiser.  Messages 
of  the  mass  media  are  based  on  the  indus¬ 
trial  organizing  principle  of  mass  distribu¬ 
tion.  This  order  has  endured  because 
there  has  been  no  demand  for  an  alterna¬ 
tive.  Because  people  did  not  have  access 
to  the  media,  they  could  not  disseminate 
alternatives  to  a  mass  audience.  Dr.  Vallee 
argues  that  mass  media  stems  from  it’s 
control  by  sectarian  interest  groups  which 
avoid  two-way  communications. 

Now,  two-way  mass  communication 
is  possible  within  the  context  of  today’s 
technology.  Such  a  communications  sys¬ 
tem  exists  because  inexpensive  micro¬ 
computers  and  ultra-fast  communications 
channels  operating  in  real  time  are  now 
available. 

Vallee  poses  a  choice  between  the 
“Digital  Society”  versus  the  “Grapevine 
Society.”  In  the  Digital  Society,  large 
computer  systems  are  repressive  devices 
which  reduce  people  to  statistics.  Usage  is 
highly  restricted  to  governments  and  cor¬ 
porations  without  any  public  access.  The 
Grapevine,  however,  allows  people  to 
build  networks  configured  around  per¬ 
sonal  computers,  new  cable  TV  services 
with  access  to  data  bases  and  information 
services.  More  importantly,  these  systems 
will  be  based  upon  the  users’  own  inter¬ 
ests.  Vallee  projects  that  these  networks 
will  become  gateways  to  other  minds, 
windows  to  other  landscapes. 

Vallee  began  his  career  as  a  computer 
scientist  tracking  Sputnik’s  orbits  on  a 


used  IBM  659  in  Paris.  He  subsequently 
participated  in  the  design  and  develop¬ 
ment  of  computer  networks.  This  back¬ 
ground  provides  many  clever  anecdotes 
for  a  shrewd  appraisal  of  human  interac¬ 
tion  with  computers. 

Vallee  traces  computer  development 
from  the  work  of  Zuse  and  other  German 
scientists  prior  to  World  War  II  through 
today’s  familiar  and  ever  more  present 
personal  computers.  When  the  billion - 
dollar  ENIAC  suddenly  failed,  the  pro¬ 
blem  was  traced  to  a  dead  moth  trapped 
in  a  relay.  This  event  gave  rise  to  the 
word  “bug,”  meaning  “error.”  He  also 
recounts  the  humor  at  meeting  the  person 
who  first  suggested  that  perhaps  comput¬ 
er  programs  needed  a  “stop”  command, 
something  we  take  for  granted  now. 

Of  course,  Vallee  does  not  spare  us 
from  some  of  the  more  conspicuous  time 
wastes.  During  the  fifties,  university  com¬ 
puting  departments  volunteered  to  assist 
the  Pentagon  in  the  translation  of  volumi¬ 
nous  amounts  of  Russian  scientific  litera¬ 
ture.  But,  alas,  all  those  millions  of  dol¬ 
lars  were  actually  spent  on  retranslating 
tons  of  Rand  Corporation  and  similar 
“think  tank”  publications  which  the  Rus¬ 
sians  had  translated  from  English! 

Vallee  gleefully  goes  into  great  detail 
about  the  failure  of  Management  Infor¬ 
mation  Systems,  MIS.  He  contends  that 
they  were  designed  for  the  purpose  of 
making  rational  decisions  about  the 
economics  of  running  a  business.  How¬ 
ever,  in  the  real  world,  business  is  not  run 
on  a  rational  basis  with  the  luxury  of 
scientific  tests.  Managers  make  decisions 
under  great  stress  and  uncertainty.  Their 
decisions  are  often  based  upon  esthetic 
and  intuitive  responses.  His  experience  of 
upper  management  was  of  elegant  execu¬ 
tives  discussing  Sartre  and  Nabokov  over 
tea. 

Surely  the  most  interesting  thing 
about  computers  is  the  variety  of  human 
responses.  Vallee  takes  a  closer  look  at 
the  nature  of  information  and  how  we 
humans  relate  to  it.  Computers  do  not 
actually  store  “information,”  but  rather 
“data.”  Information  is  a  subjective  quali¬ 
ty  dependent  upon  who  is  examining  the 
data.  Data  becomes  information  only 
after  someone  asks  a  question  about  it. 
Vallee  draws  the  analogy  of  the  doctor, 
nurse  and  hospital  administrator  review¬ 
ing  a  patient’s  records.  Each  person  recog¬ 
nizes  only  specific  parts  of  that  “data”  as 
“information.”  In  this  context,  it  is  easy 
to  recognize  a  database  as  a  power  center. 
Vallee  contends  that  an  information  cen¬ 
ter  is  primarily  a  social  system.  It  is  the 
responsibility  of  system  builders  and 
users  to  humanize  these  machines.  Too 
often,  computer  scientists  have  built 
systems  which  required  “well- trained 
humans.” 

Vallee  tells  an  anecdote  of  a  visit  to 
Russia.  He  carried  along  a  stack  of  IBM 


cards  coded  into  a  simple  program  which 
might  generate  a  dialogue  with  the  Rus¬ 
sians.  Much  to  his  amazement,  he  dis¬ 
covered  that  the  Russians  were  more 
interested  in  the  cards  than  the  program. 
Although  the  Russians  used  the  same 
shape  and  size  of  cards,  each  of  the  80 
columns  was  punched  to  maximum  effi¬ 
ciency.  Each  column  had  more  than  one 
character.  So  the  Russians  could  never 
tell  visually  what  information  or  errors 
appeared  on  the  card.  Vallee  makes  the 
point  that  extending  technology  to 
“rational”  Emits  completely  leaves  out 
the  human  element. 

Somewhere  in  his  career,  Vallee 
realized  that  artificial  intelligence  had  a 
fundamental  fallacy.  Artificial  intelli¬ 
gence  tries  “to  emulate  nature,  it  wants 
to  approximate  what  Man  does.  Imitation 
of  nature  is  bad  engineering.”  Man  does 
not  fly  by  emulating  nature  and  strapping 
on  wings.  Man  flies  by  putting  a  400 
horsepower  engine  on  a  door.  Nature 
never  created  the  Boeing  747,  because 
a  creature  that  flew  700  mph  at  40,000 
feet  was  not  needed.  “How  would  such 
an  animal  feed  itself?” 

Vallee  questions  the  very  nature  of 
intelligence.  Perhaps  Mother  Nature  “has 
never  needed  an  intelligent  animal  and 
accordingly,  has  never  bothered  to  de¬ 
velop  one.”  When  a  truly  intelligent  ma¬ 
chine  is  built,  it  will  be  based  on  princi¬ 
ples  different  from  Man’s  mind. 

Vallee  delights  in  satirizing  various 
systems  developers.  When  a  user  con¬ 
fronts  a  programmer  with  a  bug,  a  likely 
response  is  a  “fix-up”  with  another  com¬ 
mand.  Later,  the  programmer  attends 
computer  conferences  and  extols  the 
“power”  of  his  system.  Vallee  prefers  to 
take  a  large  system  and  “sculpt”  it  down 
to  a  facile  and  “friendly”  size.  He  also 
pokes  fun  at  all  the  silly  things  designers 
have  done  with  computer  keyboards. 

“Grapevine”  networks  based  on 
phone  lines  and  microcomputers  are  a 
subject  dear  to  Vallee’s  heart.  He  gives  us 
a  mini-history  of  computer  crime  and 
phone  phreaking.  He  visits  Chip  Tango,  a 
teenage  system  “cracker.”  Chip  intro¬ 
duces  Vallee  to  the  “underground  net¬ 
work.”  No  longer  do  people  conference 
over  private  networks  about  “bytes  and 
bits.”  Areas  of  interest  now  range  widely 
over  topics  such  as  gay  sex,  music,  NASA, 
jokes,  gardening  and  software  piracy.  As 
wonderful  as  such  networks  appear, 
Vallee  points  out  a  few  hidden  dangers.  If 
every  home  had  a  terminal,  the  phone 
lines  would  be  rapidly  overloaded.  Ma 
Bell  never  designed  the  phone  system  for 
such  an  interaction,  and  cable  TV  reaches 
only  about  20  percent  of  American 
homes.  Moreover,  it  is  unlikely  that 
Americans  will  ever  be  able  to  use  cable 
in  a  truly  two-way  interactive  system. 
Vallee  also  fears  that  such  a  worldwide 
communication  system  may  accelerate  an 
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already  deteriorating  sense  of  trust  in 
society. 

Lest  readers  of  this  review  get  the  im¬ 
pression  that  Vallee’s  sense  of  the 
“Grapevine  Network”  is  all  gloom  and 
doom,  relax.  In  the  final  chapter,  he 
meets  Dr.  Breeze,  a  Washington  bureau¬ 
crat  who  turns  into  a  gnome.  Lovers  of 
adventure  games  will  delight  in  this  en¬ 
counter.  Dr.  Breeze  makes  some  interest¬ 
ing  observations  about  ants,  and  he  grants 
some  mighty  powerful  wishes. 

Readers  who  would  like  a  first-hand 
accounting  of  the  history  and  develop¬ 
ment  of  computer  networks  will  enjoy 
this  highly  amusing  book.  Jacques  Vallee 
certainly  focuses  on  the  relevant  socio¬ 
logical  issues  of  network  systems. 


The  Online  Micro -Software 
Guide  and  Directory  1983/84 
Edited  by  Helen  Gordon 
Published  by  Publications  &  Conferences 
for  the  Information  Industry,  11 
Tannery  Lane,  Weston,  CT  06883 
$40.00 

Reviewed  by  Hank  Harrison 

We  always  look  forward  to  the  arrival 
of  the  Online  Directory.  This  reference 
work,  although  expensive,  is  of  great  val¬ 
ue  to  anyone  working  in  the  reference 
end  of  the  software  business.  It  is  not 
only  a  sort  of  Whole  Earth  catalog  of  a- 
vailable  software  for  all  available  systems, 
but  it  is  an  education  in  itself.  It  is  in  fact 
a  data  base  for  software  and  hardware. 

The  Online  Directory  was  edited  spe¬ 
cifically  to  meet  the  needs  of  librarians 
and  information  managers.  It  has  feature 
articles  on  choosing  terminals  and  micro¬ 
computers.  Terminals  are  handled  by 
Janet  Bruman,  who  handles  terminal  eval¬ 
uation  for  the  California  Library  Author¬ 
ity  for  Systems  and  Services  (class)  and 
Dennis  Cagan,  President  of  the  David 
Jamison  Carlisle  Corp.,  one  of  the  largest 
American  equipment  brokers.  The  micro¬ 
computer  selection  guide  is  by  John  C. 
Blair  Jr.,  Computer  Applications  Librari¬ 
an  at  Texas  A&M  Medical  Center  and 
author  of  the  micro  columns  in  both  the 
Online  and  Database  magazines. 

The  directory  also  contains  equip¬ 
ment  specifications  for  over  60  teleprinter 
terminals,  70  video  terminals,  30  printers, 
40  modems  and  over  65  microcomputers, 
plus  a  data  base  comparison  chart. 

The  sales  and  service  office  portion 
of  the  directory  is  an  alphabetical  listing 
of  over  1500  service  agents  both  U.S.  and 
international. 

The  major  criticism  of  the  catalog  is 
its  thrown-together  appearance.  For  that 
price  a  bit  of  Lettraset  could  go  a  long 
way.  The  major  titles  and  catagories  are 
not  boldfaced  and  it  does  require  some 
plowing  through. 


CRUNCHERS-21  —  Simple  Games 
for  the  Timex/Sinclair  1000  2x 
By  Yin  Chiu  and  Henry  Mullish 
Published  by  McGraw-Hill 
$8.95,  137  pp. 

Reviewed  by  Trina  Watson 

This  little  gem  is  an  ideal  small  edu¬ 
cation  book,  although  priced  a  bit  too 
high  in  this  reviewers  opinion. 

CRUNCHERS  contains  twenty-one 
original  games  programmed  in  the  T/S 
1000’s  version  of  the  Basic  language.  Not 
only  are  the  games  intriguing  and  enter¬ 
taining,  they  also  provide  an  informative 
introduction  to  general  programming, 
which  is  the  main  attraction  of  the  book, 
and  all  of  the  programs  work. 

All  twenty-one  games  are  fully  ex¬ 
plained  for  the  absolute  beginner.  For  the 
advanced  reader  there  are  suggestions  of 
how  to  modify  and  enhance  the  programs. 
Explicit  instructions  are  given  on  entering, 
editing  and  running  programs,  saving  pro¬ 
grams  on  a  tape  recorder  and  loading  pro¬ 
grams  into  the  computer  from  tape.  The 
plastic  comb  binding  ensures  that  the 
book  will  be  open  flat  on  a  desk,  a  major 
convenience  for  a  person  who  is  entering 
the  programs  into  the  computer. 

The  experience  gained  in  becoming 
familiar  with  these  programs  should  be 
able  to  be  put  to  direct  advantage  in  regu¬ 
lar  programming  situtations. 
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OF  INTEREST 


by  Michael  Wiesenberg 


Trends 

Did  you  see  Hewlett-Packard’s  an¬ 
nouncement  of  its  new  32-bit  super¬ 
minis,  the  HP  9000  family?  Mainframe 
power  at  each  networked  workstation 
(Ethernet-compatible  and  able  to  com¬ 
municate  with  other  families  of  HP 
computers,  like  3000s,  1000s,  125 
series,  and  the  new  200  series),  using 
UNIX  or  BASIC  operating  systems. 
With  built-in  10  Mb  Winchester  and 
printer,  256K  floppy  drive,  color  or 
monochrome  graphics  CRT,  the  sys¬ 
tem  fits  easily  on  a  desk-top,  or  is 
available  in  rack-mountable  box  or 
cabinet.  Offering  up  to  three  CPUs, 
languages  including  C,  FORTRAN  77, 
Pascal,  macro  assembler,  and  compiled 
BASIC,  a  symbolic  debugger,  engineer¬ 
ing  and  scientific  software,  the  9000 
costs  from  $28,250  to  $64,565.  A  lot, 
you  say?  Yes,  but  the  low-end  VAX 
starts  at  $50,000  and  the  high-end 
starts  at  over  $210,000.  This  informa¬ 
tion  should  interest  Dr.  Dobb 's  readers 
because  it  suggests  that  32-bit  systems 
will  soon  be  available  to  personal  com¬ 
puter  users  at  reasonable  prices.  Read¬ 
er  Service  No.  101. 

A  New  York  City  bank  has  offered 
ATARI  800s  as  an  inducement  to  sav¬ 
ings  instead  of  Crocker  Spaniels  and 
other  fuzzy  bank  critters.  It  remains  to 
be  seen  if  Dry  Dock  Savings  Bank’s 
plan  made  them  the  largest  retail  dis¬ 
tributor  of  home  computers  in  the 
country  over  the  Christmas  season  (the 
offer  was  good  till  the  end  of  ‘82),  as 
they  claimed.  Either  deposit  X  thou¬ 
sands  of  dollars  and  get  an  Atari  Edu¬ 
cation  and  Entertainment  System  or 
Home/Office  Management  System  in 
lieu  of  interest,  or  buy  a  system  at  re¬ 
duced  price.  Atari  has  more  informa¬ 
tion  on  this.  Reader  Service  No.  103. 


Fight  Self  Pollution 

Don’t  let  your  system  pollute  it¬ 
self!  (Electrically,  that  is.)  Eliminate 
AC  power  line  “pollution”  (noise, 
hash,  and  surges  and  spikes  from  light¬ 
ning  and  nearby  heavy  machinery) 
with  the  Magnum  Isolator  from  Elec¬ 
tronic  Specialists,  Inc.  Each  of  the 
four  “individually  quad-Pi  filtered” 
AC  sockets  handles  a  1000-watt  load, 
or  1875  watts  on  the  entire  device. 
$181.95.  Reader  Service  No.  105. 


Power  to  Spare 

For  ultimate  safety,  you’ll  want 
Standby  Power  System  (SPS)  from 
SAFT  America.  The  Model  SPS0200 
battery/inverter  system  supplies  200 
VA  of  emergency  AC  power  at  a  nomi¬ 
nal  117  volts  for  20  minutes,  and  the 
Model  SPS0400  supplies  400  VA  for 
10  minutes.  It  cuts  in  within  4  to  6 
milliseconds  (within  a  half  cycle)  when¬ 
ever  line  voltage  drops  below  102.  The 
SPS  has  an  outlet  signal  to  trigger  soft¬ 
ware  to  start  an  automatic  emergency 
shutdown,  or  safely  store  your  data  to 
disk  and  manually  shut  down  your  sys¬ 
tem  until  power  is  restored.  Output 
voltage  ranges  from  100  to  250,  and 
power  output  is  50  or  60  Hz.  The  SPS 
also  protects  against  spikes  and  tran¬ 
sients  in  voltage.  Each  unit  is  about 
the  size  and  weight  of  a  car  battery. 
$600  for  the  SPS0200,  and  $800  for 
the  SPS0400.  Reader  Service  No.  107. 


160  Mb  Winchesters 

Forget  those  disk  drives  that  offer 
only  five  megabytes  and  cost  $2495 
and  up.  The  Disctron  D-1600  from 
Disctron,  Inc.,  is  an  8-inch  Winchester 
fixed-disk  drive  with  160  megabytes 
(unformatted),  currently  available 
only  on  the  OEM  market  for  $1980. 
Thin- film  plating  technology  stores 
data  on  seven  surfaces,  each  with  a  ded¬ 
icated  read/write  head,  of  four  fixed 
disks,  with  the  eighth  for  track  and  ser¬ 
vo  information.  Disctron  also  offers  a 
10.6  Mb  8-inch  Winchester  with  re¬ 
movable  cartridge  and  an  8 -inch  fixed 
disc  with  42.4  Mb,  both  formatted, 
and  5‘A-inch  drives  with  6  through  26 
Mb  (unformatted).  Reader  Service  No. 
109. 


Sex-Change  Operations 

Reverse  the  gender  of  any  RS232 
j  line  for  compatibility  between  any  ac- 
[  cessories  with  Gender  Reversers  from 
B  &  B  Electronics.  Two  models,  one 
with  two  male  and  the  other  with  two 
female  ends,  each  interconnects  all  25 
pins,  each  for  $19.95  postpaid  (specify 
which),  or  both  for  $34.95.  And,  while 
you’re  at  it,  connect  any  two  RS232 
devices  in  any  pattern  with  B  &  B’s 
Wiring  Adapter,  that  includes  ten  plug¬ 
in  jumper  wires,  for  $24.95.  B  &  B 


also  offers  a  free  illustrated  catalog  of 
interface  and  monitoring  equipment. 

Reader  Service  No.  Ill. 


Undocumented  But  Well- 
Substantiated  Rumor 

You  know  that  Atari  400  or  800 
you  got  for  the  kids  for  games,  and 
that  only  comes  out  at  holiday  time? 
Does  it  have  a  disk  drive?  Bring  the 
“toy”  out  of  the  mothballs!  I’ve  just 
heard  a  well-substantiated  rumor  that 
you  will  soon  be  able  to  add  a  black 
box  and  a  card  for  under  $500  that 
will  let  you  run  CP/M  and,  of  course, 
all  the  applications  that  run  under 
CP/M. 


Attachment  to  Your  Rumor 

And  to  get  a  disk  drive  for  your 
Atari  for  $488,  Percom  Data  offers  the 
AT-88,  introduced  with  the  wonderful 
quote,  “We’ve  more  than  a  fond  attach¬ 
ment  for  your  Atari.”  The  single¬ 
density  drive  has  88  formatted  K,  its 
own  power  supply,  and  plugs  directly 
into  the  Atari  400/800.  You  get  the 
OS  A/Plus  operating  system  thrown  in; 
the  drive  can  also  use  Atari  operating 
system  software  without  modification. 
Percom  has  also  lowered  the  price  on 
its  double- density  drives  from  $799  to 
$699.  Reader  Service  No.  113. 


New  S  - 100  System 

MASTERMAX,  from  John  D. 
Owens  Associates,  is  a  four-slot  S-100 
Z-80  system  with  two  8 -inch  floppies, 
a  single-card  computer  with  CP/M  or 
TurboDOS.  The  four-channel  DMA 
controller  runs  a  speedy  OS,  while  disk 
emulation  allows  quick  file  access.  Up 
to  four  users  can  access  the  same  bus 
and  data  bus,  using  TurboDOS  multi¬ 
user  OS,  which  is  compatible  with  CP/M 
2.2.  You  get  a  4  MHz  Z-80,  64K  RAM 
with  bank  select,  four  I/O  ports  (two 
RS232  serial  with  one  channel  pro¬ 
grammable  in  DMA,  interrupt,  or 
programmed  mode,  and  two  parallel), 
memory  management  of  up  to  16  Mb 
system  memory,  and  eight  vectored 
priority  interrupts  that  chain  with  I/O 
interrupts  to  use  the  Z-80’s  interrupts. 
The  standard  drives  are  single-sided, 
double-density,  but  you  can  also  get 
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double-sided,  double-density;  the  disk 
controller  handles  both  formats  and 
controls  up  to  four  drives,  5 %-  and  8- 
inch  floppies  or  hard  disk.  Reader 
Service  No.  115. 


Software 

Cloned  versions  of  the  two  most 
popular  video  arcade  games  are  availa¬ 
ble  for  CP/M  from  California  Digital 
Engineering.  Catch-Um  features  a  dot- 
eater  chased  by  vicious  letters  through 
a  maze  and  Ladder  sends  you  up  lad¬ 
ders  after  a  prize  while  dodging  O’s 
rolling  down  from  above.  Customize 
your  keyboard  to  use  any  keys  for  up, 
down,  left,  right,  and  jump.  You  also 
get  a  personalization  program  to  tailor 
the  games  in  less  than  a  minute  to  any 
terminal  with  direct  cursor  addressing. 
Each  costs  $24.95,  or  both  for  $39.95. 
Specify  format.  CDE  also  offers  a 
wonderful  combination  word  proces¬ 
sor,  text  formatter,  mailing  label  and 
database  program  for  CP/M  or  North- 
Star  DOS  for  $89,  a  library  of  Z-80 
assembly  language  subroutines  for 
$34.95,  a  debugging  monitor  for 
North  Star  DOS  that  examines  and  al¬ 
ters  memory  and  registers,  sets  up  to 
three  break  points,  inputs  and  outputs 
directly  to  I/O  ports,  and  renames  files 
for  $24.95,  and  Original  Adventure  for 
most  systems  (and  the  fastest -running 
available,  they  say)  for  $29.95.  Reader 
Service  No.  1 17. 

Everyone’s  talking  UNIX  these 
days.  We’ve  seen  UNIX -/ike  operating 
systems  for  the  IBM  PC,  but  Ventur- 
Com’s  Project  Viking  offers  one  of  the 
first  “genuine”  UNIXs  for  the  PC.  The 
Viking  package  includes  Venix  (a  real¬ 
time  superset  of  System  III  UNIX), 
the  FinalWord  word  processor,  Logix 
relational  DBMS,  and  VenturCom’s 
Graphix  package.  Developed  on  DEC’s 
1 1/23,  and  also  available  for  the  DEC 
VAX,  PDP- 1 1 ,  DEC  1 1  /2,  Sony  PC, 
and  other  8086  computers,  Viking 
costs  $500  for  the  IBM  PC.  Reader 
Service  No.  119. 


Flying  Ice  Cream? 

Vanilla  Pilot  is  a  full-featured  Pi¬ 
lot  language,  including  Turtle  Graphics, 
for  Commodore  4000,  8000,  9000, 
and  Commodore-64.  You  also  get 
a  Vanilla  Pilot  editor  to  use  with 
the  computer’s  screen  editor,  adding 
commands  such  as  FIND/CHANGE, 
TRACE,  disk  and  cassette  I/O  com¬ 
mands,  LOAD  with  append  option, 
and  RUN  with  load  and  execute  op¬ 
tion.  The  manual  was  written  by  “ex¬ 
perienced  educators  and  was  carefully 
designed  for  clarity  and  easy  reading.” 
(So  they  say,  but,  as  a  technical  writer, 


/  say  I’ll  believe  it  when  I  see  it.  And 
what  are  “experienced  educators”?) 
Get  Vanilla  Pilot  from  your  Commo¬ 
dore  dealer  or  Tamarack  Software  for 
only  $29.95.  (Well,  the  price  is  right.) 
Reader  Service  No.  121. 


Connections 

Transfer  files  from  your  TRS  80 
Model  I  or  III  to  your  IBM  PC  (you  do 
have  both,  don’t  you?)  with  the  com¬ 
munications  package  from  Personal 
Computer  Products.  You  get  programs 
for  both  systems,  including  a  verifica¬ 
tion  program,  and  an  adapter  to  con¬ 
nect  the  systems.  Files  can  be  of  any 
length  and  can  be  concatenated.  Trans¬ 
mission  baud  rates  range  from  1 10  to 
9600.  A  user’s  manual  contains,  in 
addition  to  operating  instructions,  pro¬ 
gram  conversion  tips.  All  this  for 
$39.95.  Reader  Service  No.  123. 

The  Apple-IBM  Connection  from 
Alpha  Software  Corporation  transfers 
information  between  (what  else?) 
Apple  II  and  IBM  PC.  You  get  a  floppy 
for  each  machine,  and  connect  by  di¬ 
rect  cable  or  modem.  Transfer  rate  is 
up  to  100  characters  per  second. 
Either  machine  operates  in  “master” 
or  “slave”  mode,  so  you  can  control 
communications  at  either  end.  With  an 
automatic  answering  modem,  you  can 
make  a  long-distance  transfer  over  the 
phone  lines  by  yourself.  Error-checking 
procedures  ensure  integrity  of  the  da¬ 
ta.  You  can  transfer  any  kind  of  files, 
including  VisiCalc  (saving  much  rede¬ 
velopment  time),  and  use  the  package 
to  transmit  electronic  mail  between 
these  previously  incompatible  compu¬ 
ters,  as  well  as  between  Apples  and 
between  PCs.  The  documentation  is 
written  for  business  people  and  profes¬ 
sionals,  we  are  told,  and  the  package 
comes  with  a  tape  that  interactively 
introduces  the  product.  The  program 
itself  uses  English  commands  and  is 
menu-driven.  $195.  Reader  Service 
No.  125. 


Other  Stuff 

Store  80  514-inch  floppies  in  the 
Safer  Floppy  Disk  Storage  System 
from  MC2.  For  $77  you  get  a  lockable 
plastic  filing  cabinet  (13.8  by  8  by  6.5 
inches),  suspension  clips  for  a  suspend¬ 
ed  filing  system,  dividers,  reference 
cards,  and  switch -operated  retaining 
bars.  Disks  are  positioned  with  program 
information  visible  and  the  housing 
prevents  dust  contamination.  Reader 
Service  No.  129. 

Get  on-line  information  about 
microcomputer  magazine  articles  and 
mini-  and  microcomputer  software 


from  Dialog  Information  Services,  Inc. 
Search  the  Microcomputer  Index, 
cross-referencing  articles  from  thirty- 
five  magazines  about  microcomputers, 
software  and  book  reviews,  applica¬ 
tions,  and  new  product  descriptions 
(will  my  column  be  listed?,  I  wonder) 
for  $45  per  connect  hour,  and  the  In¬ 
ternational  Software  Directory  for  $60 
per  connect  hour.  Initially  10,000  re¬ 
cords,  it  is  updated  monthly.  Dialog’s 
over  160  databases  of  over  60  million 
records  include  Compendex,  abstracts 
from  over  3500  engineering  and  scien¬ 
tific  journals,  conference  reports,  and 
government  publications,  and  IN  SPEC, 
which  they  claim  is  the  “largest  Eng¬ 
lish-language  database  covering  phy¬ 
sics,  electrotechnology,  computers, 
and  control.”  Reader  Service  No.  131. 


Remember  the  President’s 
Analyst? 

The  phone  company  rather  than 
cable  companies  stands  to  profit  the 
most  from  the  growth  of  home  video 
services,  American  Family  predicts  in 
its  monthly  “Families  and  Telematics” 
column  in  the  December  1982  issue. 

The  phone  company  will  deliver 
most  of  the  $38  billion  in  new  services 
projected  annually  by  1990- more 
than  triple  the  value  of  entertainment 
services  by  then.  This  is  because  the 
phone  company  can  do  this  more 
cheaply,  more  reliably,  more  privately, 
and  with  fewer  restrictions  than  can 
cable,  or  so  claims  the  phone  company. 


And  He  Even  Looks  a  Bit  Like 
Robbie  the  Robot 

RB  Robot  Corporation  makes  the 
RB5X  intelligent  robot  with  an  RS232 
interface  to  connect  to  most  micros 
for  program  entry  and  data  transfer  (at 
1200  baud).  RB5X  learns  from  exper¬ 
ience,  has  its  own  processor  (National 
Semiconductor’s  INS  8073),  memory 
(8K  standard),  programs  (in  Tiny  BA¬ 
SIC),  and  tactile  sensors.  It  senses 
when  its  own  batteries  (RB  supplies 
rechargeable  C  and  D  batteries,  four  of 
each)  are  low,  automatically  finding  its 
battery  charger,  recharging,  and  then 
resuming  its  peregrinations.  Your  basic 
stripped  down  RB5X  costs  $1 195 ;  you 
can  add  16K  more  memory,  a  Polaroid 
Rangefinder  sonar  sensor,  and  a  pro¬ 
grammable  flashing  light  for  $295. 
Coming  soon  are  a  mechanical  arm, 
voice  synthesizer,  and  radio  communi¬ 
cations  between  robots.  Reader  Ser¬ 
vice  No.  127. 
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Calls  for  Papers 

Australian  Computer  Conference 

Those  among  us  who  are  contem¬ 
plating  defection  to  a  more  tranquil 
clime  may  wish  to  submit  papers  to 
the  I  Oth  Australian  Computer  Confer¬ 
ence  which  is  being  held  September  1 2- 
15,  1983,  in  Melbourne.  Papers  are 
solicited  in  the  following  major  areas: 
Stream  I 

The  Trials,  Tribulations  and  Tri¬ 
umphs  of  the  Manufacture  of  Hardware 
and  Software.  Papers  may  be  on  finan¬ 
cial,  marketing,  technical,  managerial, 
research-development,  educational  or 
legal  topics.  Any  other  topic  will  be 
considered. 

Stream  II 

The  Application  of  Computers  in 
Government,  Commerce,  Small  Busi¬ 
ness,  Education  or  Industry  for  all  sizes 
of  systems,  as  well  as  mixtures  of  mi¬ 
crosand  large  machines.  Topics  include 
data  base  management,  communica¬ 
tions,  graphics,  and  office  automation. 
Any  other  topic  will  be  considered. 


Stream  III 

Managerial  Aspects  of  Computing, 
including  staff  education,  objective 
settings,  audit  and  security,  feasibility 
studies,  staffing  and  motivating,  time 
management,  planning  and  controlling, 
documenting  systems,  estimating  and 
budget  setting,  and  social  and  legal 
responsibilities.  Any  other  topic  will 
be  considered. 

Stream  IV 

New  Concepts  in  Computing: 
overview  tutorials;  data  bases  (includ¬ 
ing  distributed  DB);  software  compo¬ 
nents,  system  builders  and  portability; 
research/development  presentations; 
fourth  generation  languages;  communi¬ 
cations/satellite/packet  switching/local 
area  networks;  artificial  intelligence; 
new  computer  architecture;  informa¬ 
tion  analysis;  and  telematics. 

Stream  V 

Schools  Symposium.  Topics  from 
every  sphere  of  computing  relevant  to 
school  students  and  teachers  of  com¬ 
puting. 


Stream  VI 

The  Development  and  Application 
of  Graphic  Systems:  application  of 
current  technology  to  all  spheres  but 
particularly  to  the  development  of 
earth  resources;  and  new  developments 
and  research  into  graphics  software 
and  hardware. 

An  abstract  of  the  paper  up  to 
1000  words  must  be  submitted  by 
January  1,  1983.  All  communications 
indicating  the  intention  to  submit  a 
paper  will  be  answered.  A  draft  paper 
must  be  in  by  March  1,  1983.  The 
final  typescript  paper  must  be  sub¬ 
mitted  by  June  14,  1983. 

Address  all  correspondence  to: 
Professor  A.  Y.  Montgomery,  10  ACC, 
P.O.  Box  4063,  Mail  Exchange,  Mel¬ 
bourne,  Victoria,  3001  Australia. 

Association  for  Computational 
Linguistics 

The  21st  annual  meeting  of  the 
|  Association  for  Computational  Lin¬ 
guistics  will  be  held  June  1 5-17,  1983, 
at  the  Massachusetts  Institute  of  Tech¬ 
nology,  Cambridge,  Massachusetts. 

Papers  for  the  meeting  are  soli¬ 
cited  on  linguistically  and  computa¬ 
tionally  significant  topics,  including 
but  not  limited  to  the  following: 

•  Syntax,  parsing,  and  language  gen¬ 
eration,  including  aspects  of  lin¬ 
guistic  theories  relevant  to  compu¬ 
tational  models. 

•  Computational  semantics,  including 
logic,  reference,  anaphora,  and 
metaphor. 

•  Discourse  analysis  and  speech  acts. 

•  Representation  of  knowledge,  de¬ 
duction,  and  planning  as  they  relate 
to  language  understanding  or  pro¬ 
duction. 

•  Speech  analysis  and  synthesis. 

•  Machine  translation,  machine-aided 
translation,  and  automated  diction¬ 
aries. 

•  Formal  foundations  of  computa¬ 
tional  linguistics. 

•  Applied  computational  linguistics. 

•  Software  tools  for  computational 
linguistics. 

Authors  wishing  to  present  a  pa¬ 
per  should  submit  six  copies  of  a  five- 
I  to  eight-page  summary,  double-spaced, 
by  February  1,  1983  to:  Mitchell 
Marcus,  2D-443,  Bell  Laboratories, 
600  Mountain  Avenue,  Murray  Hill, 
New  Jersey  07974,  USA;  (20 1 )  582- 
8948. 

It  is  important  that  the  summary 
contain  sufficient  information,  includ¬ 
ing  references  to  relevant  literature, 
to  convey  the  new  ideas  and  allow  the 
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program  committee  to  determine  the 
scope  of  the  work.  Authors  should 
clearly  indicate  to  what  extent  the 
work  is  complete  and,  if  relevant,  to 
what  extent  it  has  been  implemented. 

A  summary  exceeding  eight  double¬ 
spaced  pages  in  length  may  not  receive 
the  attention  it  deserves. 

All  submissions  will  be  read  by 
the  program  committee:  Mitchell 
Marcus,  Bell  Laboratories,  Chair; 
Philip  Cohen,  Fairchild  Camera  and 
Instrument  Corporation;  Lauri  Kart- 
tunen,  University  of  Texas,  Austin; 
William  Mann,  USC/Information  Sci¬ 
ences  Institute;  Robert  Moore,  SRI  In¬ 
ternational;  Ann  Robinson,  Symantec; 
Robert  Wilensky,  University  of  Cali¬ 
fornia,  Berkeley. 

Authors  will  be  notified  of  the 
acceptance  of  their  papers  by  March  7, 
1983.  Full  length  versions  of  accepted 
papers  received  by  April  18,  1983  will 
be  included  in  the  Proceedings  of  the 
Conference. 

Local  arrangements  are  being  han¬ 
dled  by  Jonathan  Allen,  Department 
of  Electrical  Engineering  and  Comput¬ 
er  Science,  MIT,  Cambridge,  MA 
02139,  USA;  (617)  253-2509;  ARPA¬ 
NET  :  ja@mit-ai. 

For  other  information  about  the 
ACL,  contact  Don  Walker  (ACL),  Arti¬ 
ficial  Intelligence  Center,  SRI  Interna¬ 
tional  EJ278,  Menlo  Park,  CA  94025, 
USA;  (415)  859-3071;  ARPANET: 
walker@sri-ai. 


Goin’  to  the  Shows? 

The  first  quarter  of  1983  promises 
a  gaggle  of  computer  shows.  The  Bay 
region  will  play  host  to  three  impor¬ 
tant  microcomputer  shows.  In  the  first 
quarter,  the  International  CP/M  Con¬ 
ference,  CP/M  83,  will  be  held  in  San 
Francisco  in  January,  followed  by 
Computer  Swap  America  in  February 
in  San  Jose,  and  ending  with  The  West 
Coast  Computer  Faire  in  San  Francis¬ 
co  in  March. 

CP/M  83  is  the  first  software 
show  based  on  an  operating  system. 
CP/M,  developed  by  Gary  Kildall  of 
Digital  Research,  has  been  the  opera¬ 
ting  system  of  choice  over  the  past 
seven  years.  The  show  is  expected  to 
draw  OEM’s,  manufacturers,  distribu¬ 
tors  and  vendors  frpm  personal,  busi¬ 
ness,  office  and  scientific  microcom¬ 
puting  sectors  along  with  minicompu¬ 
ter  and  foreign  companies.  The  show 
promoters,  Northeast  Expositions,  ori¬ 
ginally  offered  300  booths,  but  de¬ 
mand  increased  the  size  of  the  show  to 


650  booths.  Admission  is  $20  and 
show  dates  are  January  21st  to  the 
23rd  (Moscone  Center,  San  Francisco). 

Computer  Swap  America,  which 
follows  CP/M  83  by  two  weeks,  is  fast 
becoming  an  outlet  for  the  entire  com¬ 
puter  industry  (micro,  mini  and  main¬ 
frame)  to  sell  overstocked,  surplus,  ob¬ 
solete,  slow-moving,  and  many  new 
products  to  computer  hobbyists.  The 
Bay  Area  has  one  of  the  largest  con¬ 
centrations  of  hobbyists  and  personal 
computer  enthusiasts  in  the  country. 
This  no-frills,  “good  times  &  good 
deals,”  mini  show  has  attracted  manu¬ 
facturers,  retailers  (computers  and 
consumer  electronics),  software  ven¬ 
dors  and  individuals  from  all  over 
America  to  sell  their  wares.  Admission 
is  $5.  The  first  of  the  swap  shows  in 
1983  will  be  held  on  February  5th, 
from  10  to  6,  at  the  Santa  Clara 
County  Fairgrounds  in  San  Jose,  Cali¬ 
fornia.  Sellers  should  call  (415)  494- 
6862  for  further  information. 

The  West  Coast  Computer  Faire, 
which  follows  in  March  (18th-20th) 
has  become  an  institution  within  per¬ 
sonal  computing  and  has  grown  right 
along  with  the  industry.  With  the  ex¬ 
ception  of  Comdex,  it  has  become  the 
most  successful  pound -for- pound 
computer  show  of  the  year- a  must 
for  vendors  and  users  alike.  The  1983 
Computer  Faire  will  be  held  in  Brooks 
Hall,  San  Francisco  Civic  Auditorium. 
Admission  is  $  15. 

Mini-  and  microcomputers,  soft¬ 
ware,  graphics,  data  and  word  proces¬ 
sing,  telecommunications,  peripheral 
equipment,  supplies  and  computer  ser¬ 
vices— all  will  be  found  at  the  Febru¬ 
ary  18th-2 1  st  Second  Annual  Pacific 
Computer  Expo  being  held  at  the  San 
Diego  Convention  and  Performing 
arts  center.  There  will  be  popular 
hands-on  workshops  conducted  by 
Radio  Shack,  Apple  Computer,  Inc. 
and  IBM  Corporation,  where  one  can 
sit  down  with  a  computer  and  evaluate 
its  ability  to  meet  your  business,  edu¬ 
cational,  home  or  personal  needs.  The 
Expo  will  feature  some  150  exhibitors 
in  70,000  square  feet  of  display  area 
which  will  include  computers, 
products  and  services  from  $10  to 
$125,000.  Expanded  seminar  sessions 
will  offer  over  1 00  presentations  cov¬ 
ering  all  aspects  of  computer  tech¬ 
nology.  Computer  music,  robots  and  a 
host  of  other  electronic  wonders  for 
business,  office  and  home  will  be  at 
the  Expo. 

The  1983  Greater  Baltimore  Ham- 
boree  and  Computerfest  will  be  held 
on  March  27th,  1983  at  the  Maryland 
State  Fairgrounds  Exhibition  Complex 
at  Timonium,  Maryland.  A  large  exhib¬ 


it  area  will  display  and  sell  the  latest 
computers  and  software  as  well  as  the 
latest  in  electronics.  Guest  speakers 
will  present  a  wide  range  of  interesting 
topics  throughout  the  day.  The  show 
will  be  open  from  8  a.m.  to  4  p.m. 
Admission  is  $3.00,  children  under  12 
are  free.  Deluxe  arrangements  are 
available  for  dealers.  Flea  market 
spaces  are  available  for  hobbyists. 
For  additional  information,  contact: 
GBH  &  C,  P.O.  Box  95,  Timonium, 
Maryland  21093-0095;  (301)  561  - 
1282. 


As  you  may  have  noticed,  the  Of  In¬ 
terest  column  is  in  a  new  format.  We 
hope  that  its  modularity  makes  it 
more  readable.  Dr.  Dobb’s  has  a  tradi¬ 
tion  of  interaction  with  and  among  its 
readership;  we  hope  that  you  will 
continue  to  respond.  -Ed. 
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mounts  of  BASIC  code  to  enable  data 
entry  and  editing.  MCDISPLAY  allows 
the  display  to  be  defined  by  fields.  The 
same  display  is  used  by  the  program 
operator  for  data  editing  as  well  as  data 
entry.  The  programmer  only  needs  to 
write  one  program  instead  of  two  or  more. 
An  entire  “screen”  of  information  is  al¬ 
ways  in  view  by  the  program  operator. 

For  further  information,  contact: 
Master  Computing,  Inc.,  P.O.  Box  17442, 
Greenville,  SC  29606;  telephone  (803) 
244-8174. 

Robot  Triplicity  at  Atari 

Atari,  that  game  show  host  that  greets 
you  (even  when  you  turn  off  your 
television  set),  that  mega-company 
founded  on  PONG,  the  company  that 
said  it  would  never  go  to  CP/M,  is  in  fact 
doing  just  that.  Dr.  Dobb’s  has  heard  the 
rumor  from  three  independent  sources. 
Now,  since  putting  three  and  three  to¬ 
gether  gets  you  nine,  the  not  so  obvious 
conclusion  is  that  Atari  is  probably  build¬ 
ing  a  robot  or  robot-like  product  which 
will  probably  run  on  CP/M.  Their  simula¬ 
tions  for  games  like  Battle  Zone  are  one 
possible  connection  too,  since  these 
“real  world”  terrain  emulating  matrices 
are  derived  from  actual  military  technolo¬ 
gy.  This  robot  will  probably  be  self¬ 
charging,  like  its  competition,  and  will  be 
programmable  to  perform  certain  house¬ 
hold  functions  such  as  smoke  sensing, 
burglar  or  intrusion  detection,  and  re¬ 
mote  telephone  stationing,  all  with 
speech  synthesis,  if  desired.  We  can’t 
wait  to  have  our  very  own  micro-mouse 
“Bot”  droid  for  under  two  grand,  but  will 
it  go  to  the  7-11  for  “munchies”  on  a 
rainy  night?  Only  time  will  tell! 

Atari’s  entry  into  the  “Bot”  market 
may  turn  out  to  be  a  moot  point  since  a 
Colorado-based  company  called  the  RB 
Robot  Corporation  is  a  full  year  ahead 
with  a  magical  little  “druid”  (droid) 
called  RB5X*.  This  guy  is  about  the  size 
of  a  wastebasket,  runs  on  Tiny  BASIC  (see 
DDJ  number  one)  and  is  available  now. 
No  matter  how  rich  they  are,  the  brains 
at  Atari  will  have  to  play  catch-up  poker, 
at  least  for  the  first  year.  The  RB5X  will 
be  growing  ahead  of  Atari,  offering  add¬ 
ons,  arms,  sensor  packs,  lasers,  etc.  Inter¬ 
estingly  enough,  Heath  has  also  announced 
its  entry  into  Robotics  and  a  Heath- Kit 
Robot  will  soon  be  available.  These  are 
the  first  companies  producing  actual 
home-available  “Bots”  for  under  $2000, 
but  the  market  is  infinitely  expandable. 

I  sure  wish  we  had  one! 

See  page  70  of  DDJ’s  Of  Interest,  this 
issue,  for  a  picture  of  the  RB5X.  -Ed. 


Peddling  In  Nice 

Chuck  Peddle,  the  developer  of  the 
Commadore  PET,  the  6502,  the  VIC,  and 
the  VICTOR  9000,  has  hinted  that  the 
European  headquarters  of  his  newly 
formed  Victor  Computer  Company 
(which  he  claims  will  be  the  third  largest 
computer  company  in  the  world  some¬ 
day)  will  not  be  in  Paris  or  its  environs, 
but  rather  in  the  more  pleasant  and  de¬ 
cidedly  nude  spot  on  the  Riviera  called 
“Nice.”  Why  not,  he  just  announced  an 
improved  Victor  9000  with  10  Mb  for 
under  $6000.  That  should  put  IBM  on 
notice.  There  is  no  doubt  that  the  new 
Victor-Sirius  system  is  a  bargain,  but  .  .  . 
“Gee,  Chuck,  will  we  really  ever  get  any 
work  done  on  the  Cote  d’Azur?” 


Very  Rair  Black  Box 

Besides  the  Victor  9000,  a  British 
company  stole  the  show  at  Comdex.  This 
gutsy  little  company,  which  licenses  a  PC 
to  ICL,  this  IBM  of  England  (although  it 
is  not  owned  by  ICL  as  some  believe), 
took  a  stand  in  the  middle  and  did  very 
well  indeed. 

The  Rair  Black  Box  is  at  least  five 
years  old.  ICL  is  new  to  the  micro  world 
and  chose  Rair  to  develop  their  new  PC, 
a  beige,  fluffy  thing  that  looks  like  a 
marshmallow.  The  Black  Box,  however, 
looks  like  a  Porsche  and  runs  as  well. 
Even  without  screen  and  keyboard,  it  is 
superior  to  any  but  the  Victor  9000  in 
this  price  range.  This  machine  can  be 
compared  to  any  16-bit  system,  and  this 
includes  the  overly-honored  IBM  PC. 

The  8 -bit  Black  Box  is  companioned 
by  the  Rair  line,  plus  a  new  16-bit  Black 
Box  still  in  production.  In  1981,  I  had 
some  hands-on  with  the  system  in  Ireland 
and  loved  it  because  it  had  a  5Mb  integral 
hard  disk,  great  fun  for  those  days  and 
ready  to  go  at  a  time  when  American 
companies  were  tinkering  with  the  idea. 
Dynabyte  was  the  first  to  do  anything 
about  it,  but  that  project  evolved  into 
their  current  “biggie”  called  the  Monarch. 

The  Black  Box  hasn’t  changed  much 
since  its  introduction.  It  is  built  to  EEC 
standards  which  take  into  consideration 
longevity  and  operational  normalcy  in 
hostile  environments.  Like  the  micropro¬ 
cessor-based  Pontiac  on  television  (the 
one  that  talks  to  the  driver),  the  Rair 
Black  Box  looks  tough  and  runs  smooth, 
but  when  you  punch  in  STAT  *.*  and  it 
returns  the  number,  14.650K,  to  the 
screen,  you  know  you’re  on  to  some¬ 
thing.  The  hard  disk  has  grown  from  5Mb 
to  16Mb  optional,  although  the  5Mb  is 
still  available.  The  hard  disks  can  be 
chained  in  increments  of  5,  10  or  16Mb. 
The  model  we  saw  at  Comdex  was  a  32Mb 
version  with  over  500K  of  RAM.  There 
is  also  a  Rair  business  computer  and  Rair 
does  its  own  R&D  and  production. 

Dr.  Dobb’s  is  currently  a  beta  instal¬ 


lation  for  the  Rair  equipment  and  the 
good  Doctor  is  reviewing  the  system  for 
next  month’s  issue.  The  350  and  360  top- 
of-the-line  Black  Boxes  use  an  8085  with 
memory  management  that  can  address  up 
to  1Mb  of  RAM. 

The  Rair  system  does  not  arrive  with 
a  keyboard  or  terminal,  but  it  was  shown 
at  Comdex  with  the  ADDS  keyboard  and 
terminal  as  featured  by  Bove  and  Rhodes 
in  the  premiere  issue  of  The  User’s  Guide. 
Rair  Black  Boxes  feature  an  advanced 
implementation  MP/M  II. 

For  further  information,  contact: 
The  Rair  Computer  Corporation,  4101 
Burton  Drive,  Santa  Clara,  CA.  Their  tele¬ 
phone  number  is  (408)  988- 1790. 

»»J 
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This  tends  to  send  you  to  a  tight  loop  in 
never-ever  land. 

Until  Digital  Research  makes  BDOS 
calls  reentrant,  do  not  try  to  trace  through 
them.  Your  best  bet  is  to  break  point  be¬ 
fore  and  after  the  call  and  examine  the 
registers.  I  hope  this  explains  the  problem 
and  will  prevent  someone  from  learning 
about  it  like  me  (painfully). 

Stephen  M.  Kenton 
Software  Consultant 
475  College 
Norman,  OK  73069 

A  Letter  From  the  Editor 

Dear  Readers: 

We  are  putting  together  an  advanced 
S-100  system.  We  have  all  of  the  compo¬ 
nents.  If  there  are  any  hardware  jockies  in 
the  San  Francisco  Bay  Area  who  would 
be  interested  in  this  project,  drop  us  a 
line.  A  small  honorarium  and  lots  of  free 
treasure  await. 

Hank  Harrison,  Editor 

•»J 
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by  Edward  M.  Mitchell 

In  the  January  issue,  Mr.  Mitchell  described  the  structure  of  a  subset  of  Ada  called 
Augusta.  This  month  he  looks  at  the  p-codes  and  at  the  p-code  interpreter  of 
Augusta. 

36  A  Small  -  C  Operating  System 

by  Brian  McKeon 

Adding  a  new  twist  to  our  continuing  coverage  of  the  development  of  Small-C, 
author  McKeon  has  provided  for  your  experimentation,  the  source  code  for  an 
operating  system  developed  with  Ron  Cain’s  Small-C  compiler. 

62  6809  Threaded  Code:  Parametrization  and  Transfer  of  Control 

by  H.  T.  Gordon 

The  author  discusses  how  careful  optimization  of  Forth- like  languages,  taking 
into  consideration  the  superlative  addressing  power  of  the  newer  CPUs,  can  result 
in  insignificant  reduction  of  timing  penalties.  He  argues  that  major  conceptual 
changes  such  as  parametrization  will  streamline  languages  and  provide  some  com¬ 
mon  core  structure  to  them. 

66  A  Common -Sense  Guide  to  Faster,  Smaller  BASIC 

by  Robert  Irving 

Speedy  CPUs  and  lots  of  RAM  are  great,  but  are  your  coding  habits  creating 
memory  bloat  and  an  idling  processor?  These  down-to-earth  guidelines  could  help 
fat  cats  and  bare  boards  alike  to  program  more  efficiently. 

71  A  Fundamental  Mistake  in  Compiler  Design 

by  Edgar  H.  Fey,  Jr. 

The  huge  size  of  recent  assemblers  and  compilers  prompted  Mr.  Fey  to  provide  us 
with  his  observations  on  the  reason  for  the  bloat,  and  some  suggestions  for  the 
reduction  of  it. 
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LETTERS 


Off  to  a  Good  Start 

Dear  Editor, 

Your  January  issue  was  stimulating  as 
usual.  Of  the  dozen  or  so  computer  jour¬ 
nals  that  arrive  every  month,  Dr.  Dobb’s 
is  one  of  the  few  that  1  always  read.  The 
good  Dr.  Dobb  deserves  particular  thanks 
for  introducing  me  to  the  Forth  language 
several  years  ago. 

On  the  whole  I  disagree  strongly  with 
Tom  Pittman’s  January  letter.  But  he 
does  have  a  valid  point  with  regard  to 
those  interminable  listings.  Everybody 
has  a  modem  these  days.  Perhaps  you 
should  consider  putting  the  program  files 
on  CompuServe  or  The  Source  or  an  in- 
house  dial-up  line.  Even  at  300  baud,  it 
sure  beats  typing. 

I  enjoyed  Ray  Duncan’s  discussion  of 
the  numeric  evaluation  of  trigonometric 
functions.  As  usual,  he  is  brief  and  cogent, 
but  on  one  point  his  trigonometry  is  a 
little  bit  rusty.  We  do  not  have  to  extract 
a  square  root  to  obtain  the  cosine.  The 
cosine  is  simply  the  sine  shifted  by  90 
degrees.  Thus  cos(x)  =  sin(x+90)  or  for 
radian  phreaks,  cos(x)  =  sin(x+PI/2). 

To  the  entire  staff  at  Dr.  Dobb’s,  I 
wish  a  successful  and  prosperous  new 
year.  Keep  up  the  good  work. 

Sincerely, 

Joseph  McDermott 
265  Bogert  Road 
River  Edge,  NJ  07661 


A  Slightly  Slicker  Fix 
for  Small -C 

Dear  Editor, 

Mr.  Macpherson  was  kind  enough  to 
send  me  a  copy  of  his  letter  to  you  ( DDJ 
#76,  pp.  10-11)  describing  a  Small-C 
bug  involving  continue  statements  within 
switch  statements.  He  was  quick  to 
fathom  the  problem  and  find  a  solution. 
After  studying  his  patch,  I  settled  on  a 
slightly  more  efficient  and  straightfor¬ 
ward  solution.  I  hope  he  won’t  mind  if  1 
recommend  this  patch  over  his  own. 

First,  in  the  function  doswitch  below 
the  call  to  addwhile  (line  184,  page  39, 
DDJ  #74),  insert  the  line 

*wqptr  +  WQLOOP  -  WQSIZ)  =  0; 

Then  change  the  following  functions  to 
read  as  shown.  Modified  lines  begin  with 
a  #  character. 

(page  42,  DDT  #74) 


dobreak()-( 
int  *ptr; 

#  if  ((ptr=readwhile(wqptr))==0) 

return ; 

modstk  ((ptr[WQSP] ),  NO); 
jump(ptr[  WQEXIT ] ); 

y 

docont()  -{ 
int  *ptr; 

#  ptr  =  wqptr; 

#  while  (1)  -[ 

#  if  ((ptr=readwhile(ptr))==0)  return; 

#  if  (ptr[WQLOOP])  break; 

#  y 

modstk((ptr[WQSP] ),  NO); 
jump(ptr[  WQLOOP] ); 

y 

(page  45,  DDJ  #74) 

delwhileO  -{ 

#  if  (wqptr  >  wq) 

wqptr=wqptr-WQSIZ ; 

h 

#  readwhile(ptr)  int  *ptr;f 

#  if  (ptr  <=  wq)  \ 

#  error(“out  of  context”); 
return  0 ; 

#  else  return  (ptr-WQSIZ); 

1- 

This  will  compile  with  the  original 
compiler,  so  those  bringing  it  up  for  the 
first  time  with  this  patch  should  have  no 
problem. 

The  response  to  my  article  has  been 
most  encouraging.  I  was  surprised  to  find 
that  a  number  of  well  known  microcom¬ 
puter  companies  are  using  the  little  com¬ 
piler.  1  am  looking  forward  to  seeing 
more  software  contributions  written  for 
Small-C. 

Sincerely, 

J.  E.  Hendrix 
Rt.  1,  Box  74-B-l 
Oxford,  MS  38655 


Augusta  Short  Circuits 

Dear  Dr.  Dobb, 

I  was  very  pleased  to  see  the  article, 
“Augusta,”  by  Edward  Mitchell.  Ada™  is 
unfortunately  “doomed  to  succeed,”  so  it 
is  good  to  see  that  those  of  us  who  live  on 
small  machines  will  be  able  to  see  all  the 
reasons  why  it  is  being  panned  by  such 
notables  as  Hoare  (“The  Emperor’s  Old 
Clothes,”  Communications  of  the  ACM, 
Vol.  24,  No.  2,  February  1981).  I  will  also 
be  interested  in  seeing  a  compiler  written 
in  BASIC,  of  all  things.  Unfortunately, 


Mr.  Mitchell  left  out  one  of  the  most 
useful  features  of  Ada,  the  package. 

However,  Mr.  Mitchell  states  that  the 
“short  circuit”  conditionals  of  Ada  are 
unusual.  I  beg  to  differ.  Many  modern 
languages,  such  as  C  and  LISP,  support 
short  circuit  evaluation  of  conditionals. 
Most  languages  (including,  notably,  Pascal) 
leave  the  question  of  whether  condition¬ 
als  short  circuit  up  to  the  implementor. 
In  fact,  one  of  the  popular  Fortran 
compilers  for  the  IBM  370  would  test 
Mr.  Mitchell’s  example  [if  (n<>0)  and 
(j/n=l)  then]  by  testing  whether  or  not 
j/n=  1 ,  and  if  that  were  false,  “short  cir¬ 
cuit”  the  test  n<>0.  This  state  of  affairs 
means  that  the  defensive  (i.e.,  smart) 
programmer  will  act  as  if  things  will  not 
be  short  circuited,  and  also  not  put  state¬ 
ments  with  side  effects  in  conditionals, 
just  in  case  things  are  short  circuited.  Af¬ 
ter  working  with  such  things,  it  is  truly 
enjoyable  to  use  something  which  lets 
you  know  what’s  going  on  —  whether  it 
Ire  C,  LISP,  or  Ada. 

Mike  Meyer 

Box  1749 

Norman,  OK  73070 

Compliments  for  Kossow 

Dear  Dr.  Dobb, 

Thanks  for  presenting  Allen  Kossow’s 
68000  cross-assembler.  Mr.  Kossow  has 
done  an  excellent  job  of  managing  the 
large  instruction  set  and  numerous  ad¬ 
dressing  modes  of  this  new  processor. 

In  the  past  I  have  made  use  of  system 
software  listings  provided  by  the  doctor. 
This  time,  however,  because  of  the  immi¬ 
nent  arrival  of  a  68 000 -based  develop¬ 
ment  system  at  my  workplace,  I  took 
advantage  of  Mr.  Kossow’s  offer.  Twenty- 
five  dollars  is  a  reasonable  copying  fee  in 
my  opinion. 

I  was  pleased  to  find  that  the  single¬ 
density  RT-1 1  diskette  contained  an  exe¬ 
cutable  file  in  addition  to  the  Fortran  and 
Macro  source  files.  Because  of  this,  I 
immediately  set  to  testing.  Five  problems 
were  discovered  using  examples  from 
68000  Assembly  Language  Programming 
by  Kane,  Hawkins  and  Leventhal  (Os- 
borne/McGraw  Hill,  1981). 

The  first  hitch  was  an  illegal  instruc¬ 
tion  trap  encountered  when  run  on  a 
PDP- 11/04.  It  was  traced  to  the  Macro 
routine  file,  specifically,  the  ASH  instruc¬ 
tion  in  routine  GETBIT.  Replacing  this 
one  instruction  with  four  (4)  ASR  R0 
instructions  cleared  things  up  nicely.  If 
you  are  using  a  DEC  processor  with  EIS 
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(Extended  Instruction  Set)  like  an  LSI- 
11/23  or  LIS- 11/34,  then  this  change  is 
unnecessary. 

The  second  problem  showed  up  as  a 
reversal  of  the  source  and  destination  reg¬ 
isters  in  all  ADDX,  SUBX,  ABCD,  and 
SBCD  instructions.  A  fix  is  as  follows: 

Replace  these  three  lines  in  subroutine 
PRCESS 

1910  IF (OP1  EA.EQ.5) 

OPSKEL=OPSKEL+8 

OPSKEL=OPSKEL+OP2DA 

OBJBUF(l)= 

OPSKEL+(OPl  DA*”  1000) 
by  inserting  these  three  lines 

OPSKEL=OPSKEL+8 
1910  OPSKEL=OPSKEL+OPl DA 
OPJBUF(l)=OPSKEL+ 
(OP2DA*”1000) 

The  third  bug  prevented  any  MOVE 
instruction  from  being  assembled  as 
MOVEQ(quick  move).  A  fix  follows: 

Replace  these  four  lines  in  subroutine 
PRCESS 

lF(lMODE.NE.3)GOTO  304 
IF(OPNWRD(3).EQ.O)  GOTO 
301 

IF(OPNWRD(3).EQ.-l )  GOTO 
301 

GOTO  304 
301  ..  . 

by  inserting  the  following  three  lines 

IF (IMODE.NE.O)  GOTO  304 
IF (OPNWRD(3).EQ.O)  GOTO 
301 

IF(OPNWRD(3).NE.-l)  GOTO 
304 

301  ..  . 

This  causes  the  assembler  to  optimize  a 
MOVE  immediate  instruction  to  the 
MOVEQ  form  only  if  the  datum  size  is 
defaulted  and  the  datum  is  in  the  legal 
range  for  MOVFQ(-129<arg<  128).  For 
a  consistent  treatment  of  quick  mode  in¬ 
structions,  the  following  change  should 
be  made  to  make  ADDQ  and  SUBQ  oper¬ 
ate  in  the  same  manner: 

insert  this  line  into  PRCESS 

IF  (IMODE.NE.O)  GOTO  536 
in  between  these  two  existing  lines 
IF(OPNFLG.EQ.  1 )  GOTO  536 

and 

IF (OPNWRD(2).GE.  l.AND. 
OPNWRD(2).LE.8)  GOTO  550 

536  ..  . 

Problem  number  four  prevented 
assembly  of  the  CMPM  form  of  the  CMP 
instruction.  A  fix  is  below: 

Replace  this  line  in  subroutine  PRCESS 
400  ..  . 

IF ((OP1  EA.EQ.5)  .AND. 
(OP2EA.EQ.5))  GOTO  480 


by  this  new  line 

IF((OPlEA.EQ.4)  .AND. 

(OP2EA.EQ.4))  GOTO  480 

A  fifth  problem  was  noted  in  assem¬ 
bly  of  the  LEA  instruction  where  the 
addressing  mode  is  register  indirect  with 
index.  An  example  is  LEA  -1(A0,D0.W), 
Al.  I  have  not  had  an  opportunity  to  ana¬ 
lyze  the  problem  any  deeper. 

My  compliments  to  Allen  Kossow.  A 
piece  of  software  of  this  size  seldom  ap¬ 
pears  with  so  few  glaring  errors.  Keep  up 
the  good  work. 

Sincerely, 

Steve  Albrecht 

Tracor  Northern  Instruments 

Middleton,  WI  53562 

Dear  Editor, 

I  have  an  ulterior  motive  for  writing. 
I  must  have  one  of  Al  Kossow’s  ( DDJ  No. 
68,  “Multi-68000s  in  a  Personal  System”) 
computers. 

I’ve  written  to  Mr.  Kossow  to  express 
my  enthusiasm.  A  project  like  his  is  an 
ambitious  one  so  I  didn’t  really  expect  an 
answer. 

Yes,  I  know  he  said  any  future  devel¬ 
opments  would  be  published  in  DDJ.  The 
point  of  this  letter  is  to  urge  DDJ  to  pub¬ 
lish  the  info  .  .  . 

Anxiously  awaiting  each  and  every 
issue  .  .  . 

Judd  Ellmers 
1  A  Rolling  Ridge  Road 
Montvale,  NJ  07645 

Editor’s  note:  We  hope  to  do  an  update 
soon.  In  the  meanwhile,  can  any  DDJ 
readers  help  us  out  on  multi-68000s? 


More  on  Graphics  Algorithms  .  .  . 

Gentlemen: 

The  vector  generation  algorithm  pub¬ 
lished  in  the  December  issue  of  DDJ  is 
not  new.  Several  years  ago,  I  purchased  a 
Houston  Instrument  plotter  and  the 
manual  included  an  implementation  in 
BASIC  of  what  was  essentially  that  algo¬ 
rithm.  I  found  the  algorithm  described  in 
one  of  the  BYTE  Books  called  Bits  and 
Pieces.  There  it  was  credited  to  somebody 
at  IBM.  Most  implementations  reduce  the 
calculation  per  step  even  further  than 
Mr.  Michalski’s  version.  Usually  F  is  ini¬ 
tialized  to  2*DY-DX  and  in  the  loop,  F  is 
tested  relative  to  zero  as  the  first  step  of 
the  loop.  If  F  is  negative,  only  X  is  incre¬ 
mented  before  the  new  point  is  plotted 
and  F  =  F+2*DY  is  calculated.  If  F  is  zero 
or  positive,  both  X  and  Y  are  incremented 
before  the  new  point  is  plotted  and 
F=F+2*DY-2*DX  is  calculated  before¬ 
hand  so  only  one  addition  per  step  is 
necessary  to  update  F.  Here  I  have  used 
the  same  notation  as  Mr.  Michalski  except 
for  using  D  instead  of  delta.  Well,  it  is  a 


good  idea  no  matter  how  many  times  it  is 
reinvented. 

This  is  the  simplest  and  probably  the 
most  useful  of  what  I  call  the  where- do- 
we-go-from-here  algorithms.  The  idea  is 
that  the  choice  of  the  next  point  to  be 
moved  to  or  set  is  limited  to  one  of  the 
eight  points  next  to  the  last  point.  This 
limitation  may  be  inherent  in  the  graphics 
device  or  imposed  to  insure  the  drawing 
of  a  continuous  line.  Knowledge  of  the 
general  direction  of  the  curve  is  used  to 
limit  the  choice  to  two  of  these  points, 
and  some  easily  calculated  error  function 
is  used  to  choose  between  the  two.  So 
far  this  straight  line  algorithm  and  the 
one  for  doing  circles  and  arcs  are  the  only 
ones  for  which  I  have  worked  out  the  de¬ 
tails  and  successfully  implemented.  I  did 
both  of  them  in  BASIC  first  and  then 
finding  this  a  bit  slow,  I  resorted  to  a 
mixture  of  Fortran  and  assembly  lan¬ 
guage.  With  that  I  was  able  to  keep  my 
plotter  going  at  close  to  its  maximum 
speed.  Although  I  have  not  yet  worked 
out  the  details,  it  appears  that  these 
techniques  could  be  extended  to  any  of 
the  conic  sections,  but  at  a  price  of  in¬ 
creasing  complexity  and  decreasing  speed. 

Another  graphics  related  matter  that 
I  have  been  planning  to  write  you  about 
is  related  to  Mr.  Taylor’s  ellipsoid  prob¬ 
lem  which  appeared  in  the  Clinic.  I  was 
one  of  those  that  sent  in  a  solution  to  his 
problem.  Ever  since  his  response  to  the 
solutions  appeared  in  the  August  issue,  I 
have  been  thinking  about  it  and  I  have 
reached  the  conclusion  that  he  posed  the 
wrong  problem.  He  talks  of  perspective 
projection  and  yet  the  problem  that  he 
posed  was  projection  parallel  to  the  Z 
axis  which  is  orthographic  projection.  I 
have  worked  out  the  solution  for  perspec¬ 
tive  projection,  but  since  it  involves  even 
more  calculation  than  the  solution  for 
orthographic  projection,  which  he  found 
to  involve  too  much  calculation  for  his 
purposes,  it  probably  will  be  of  little  use 
to  him. 

Sincerely  yours, 

David  S.  Tilton 

27  Pennacook  Street 

Manchester,  NH  03104 

.  .  .  And  Variations  on  Michalski's 

People: 

I  was  interested  in  your  simple  vector 
generation  algorithm  in  the  December 
DDJ  —  interested  because  I  had  devised 
the  same  underlying  algorithm  for  use  in 
a  mailing  list  application. 

A  businessman  has  a  mailing  list  with 
90  names  (for  example).  He  wishes  to 
send  some  promotional  material,  but  to 
only  20  people  (small  budget,  maybe). 
Therefore  he  wants  a  way  of  extracting 
20  names  from  the  list  of  90  in  an  even 
distribution. 

Hopefully,  you  can  see  that  selecting 
20  names  from  90  is  a  similar  problem  to 
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drawing  a  vector  which  rises  20 x  points 
and  runs  90  y  points. 

The  algorithm  used  in  the  mailing  list 
application  was:  Let  y  run  from  0  to  89, 
and  set  x  =  y*20div90.  X  will  increase 
slowly  from  0  to.19.  For  each  input  name 
(y),  print  it  out  only  if  the  value  of  x  has 
increased  from  the  previous  y  (integer 
arithmetic).  In  Pascal: 

var 

x,  y,  xprev  :  integer; 

begin 

xprev  :=  -1 ; 

for  y  :=  0  to  90- 1  do  begin 
getname; 

x  :=  y  *  20  div  90; 
if  x  <>  xprev  then 
putname; 
xprev  :=  x 

end 

end 

I  hope  this  shows  the  idea.  Obviously 
a  useful  program  would  use  variables  in 
place  of  90  and  20,  and  probably  would 
have  to  make  an  initial  pass  through  the 
list  to  count  how  many  names  are  there. 
The  flowchart  published  in  the  article 
uses  more  code  but  is  more  efficient  be¬ 
cause  it  eliminates  the  multiply  and 
divide  operations. 

An  amusing  variation:  The  above  pro¬ 
gram  tries  to  print  20  names,  but  if  the 
original  list  only  had  8  names,  it  would 
only  print  8.  By  replacing  the  “if’  state¬ 
ment  with  a  “for”  loop,  you  can  guaran¬ 
tee  20  printed  names  no  matter  how 
small  the  mailing  list  is  (provided  it’s  not 
empty). 

getname; 

x  :=  y  *  20  div  8 ; 

for  xprev  :=  xprev  to  x-  1  do 
putname; 

xprev  :=  x 

With  this  program,  each  of  the  8 
names  is  printed  two  or  three  times  to 
give  an  output  list  of  20  entries. 

Yours  truly, 

Peter  Raynham 
10  Camrose  Crescent 
Scarborough,  Ontario 
Canada  MIL  2B6 

Forth  Cosine  with  8087 

Dear  Editor: 

The  purpose  of  this  letter  is  twofold. 
(1)1  wish  to  share  with  your  readers  my 
enthusiasm  toward  Forth  Inc.’s  method 
of  structuring  8087  floating  point  in  their 
Forth  for  the  IBM  PC.  (2)  Since  trigono¬ 
metric  functions  are  not  included  in  Poly- 
forth  (at  least  not  in  the  version  I  own),  I 
would  like  to  put  into  public  domain  a 
program  (see  Listing  1 ,  this  page)  for  cal¬ 
culating  cosines.  Besides  being  fast  (470 
microseconds)  and  accurate  (16  digits), 


the  algorithm  I  developed  is  unusual  be¬ 
cause  it  uses  an  unspecified  8087  feature 
and  involves  no  conditional  branching. 
Thus,  the  algorithm  should  be  of  interest 
to  non-Forth  programmers. 

Forth  is  not  a  popular  floating-point 
language  and  has  no  floating-point  stan¬ 
dards.  Traditionally,  floating-point  num¬ 
bers  have  been  stored  with  integers  on  the 
parameter  stack  which  resides  in  memory. 
This  is  somewhat  inefficient  since  there 
are  no  operations  between  the  two 
numerical  types  and  one  tends  to  ob¬ 
struct  the  other,  thereby  requiring  exten¬ 
sive  stack  manipulation  in  a  floating-point 
program. 

Consider  the  8087,  a  chip  with  a 
stack  of  its  own  comprised  of  eight  80-bit 
registers  that  can  perform  most  internal 
operations  faster  than  a  64-bit  number 
can  be  transferred  to  memory.  Indeed, 
the  8087  can  swap  two  80-bit  numbers 
on  its  stack  faster  than  the  8088  can  swap 
two  16-bit  numbers  in  memory.  Clearly, 
with  the  8087,  it  would  be  a  serious 
waste  of  time  to  automatically  transfer 
8-byte  floating-point  numbers  to  a  mem¬ 
ory  stack  and  then  back  again  between 
operations. 

Forth  Inc.  has  made  a  rational  devia¬ 
tion  from  tradition  by  simply  using  the 
8087  stack  as  an  extra  Forth  stack.  It 
wouldn’t  surprise  me  if  this  chip-language 
combination  is  unbeatable  among  micro¬ 
computers  for  speed.  To  test  my  hypoth¬ 
esis,  I  invite  benchmark  challenges,  par¬ 
ticularly  from  owners  of  68000-based 
computers.  I  only  require  that  the  program 
be  a  practical  64- bit  number  cruncher 
such  as  matrix  multiplication  and  not  an 
abstraction. 

Regarding  the  cosine  algorithm,  from 
the  angle,  V,  the  8087  instruction  FPTAN 
returns  the  sides  of  a  right  triangle,  X(V) 
and  Y(V).  Intel  literature  states  the  re¬ 
striction,  “0<V<PI/4”;  however,  I 
discovered  that  my  8087  was  completely 
accurate  in  the  range  -PI/2<V<PI/2. 


Using  this  feature,  I  came  up  with  the  fol¬ 
lowing  algorithm  that  is  best  described  in 
equation  form: 

Let  U  =  Angle 

SI  *[FABS(  FABS[  FPREM 

(U,2*P1  )  ]  -  PI  )- PI/2] 

(  U,2*PI  )  ]  -  PI) -PI/2  ] 
COS(U)  =  Y(V)  /  FSQRT(  X(V)*X(V) 

+  Y(V)*Y(V)  ) 

Notice  that  multiplying  by  SI  keeps 
V  from  exceeding  its  limits.  1  have  includ¬ 
ed  an  implementation  of  this  algorithm 
using  Polyforth  assembler  mnemonics. 
The  sine  function  can  be  obtained  by  sim¬ 
ply  subtracting  PI/2  from  U. 

Sincerely  yours, 

Steven  A.  Ruzinsky 
2110  S.  Austin  Blvd. 

Cicero,  IL  60650 

(See  Listing  1  below) 

[ See  correction  in  April  issue,  page  8.  —  Ed.] 

Subscription  Glitch 

Dear  Doctor  Dobb, 

I’m  sure  you  have  heard  stories  like 
mine  many  times  before,  but  I  would  be 
grateful  if  you  eyeballed  my  output. 

I  used  to  be  a  small  microprocessor 
with  very  underdeveloped  software.  When 
I  went  to  the  beach,  big  strong  mainframes 
would  kick  sand  in  my  face  and  attractive 
young  minis  would  laugh  at  me. 

How  delighted  was  I  when  I  dis¬ 
covered  what  a  dose  of  DDJ  did  for  my 
development!  So  wonderful  were  the  re¬ 
sults,  that  it  is  little  surprise  that  I  soon 
became  addicted  to  monthly  shots  of 
DDJ.  Naturally  when  my  subscription  re¬ 
newal  became  due,  I  raced  down  to  the 
bank  at  my  fastest  baud  rate,  obtained  a 
bank  cheque  in  U.S.  dollars  for  two  years 
(yes,  I  wasn’t  going  to  risk  cold  turkey), 
and  sent  it  off  airmail  immediately. 

Can  you  imagine  my  alarm  when 
some  months  later  another  renewal  notice 


Listing  1. 

8087  Cosine  Routine  in  Polyforth. 

254 

0 

ll 

(  8087 

Cosine  in  Polyforth,  470  microsec.  ) 

LVARIABLE  SI 

o 

.9999999999999999  SI  L! 

4 

5 

CODE 

6 

COS 

FLD1  FLDPI  FSCALE  1  N>  FSTP  1  FXCH 

~7 

FPREM  1  N)  FSTP  FABS  FLD1  FCHS  FLDPI 

8 

2  N)  FSUB  -POP  FSCALE  1  N>  FSTP 

9 

1  FXCH  FABS  1  IN)  FSUB  REV  R64  SI  FMUL 

10 

FPTAN  1  N)  FLD  O  N)  FMUL  NO  1  FXCH 

1 1 

O  N)  FMUL  NO  1  N  >  FADD  FSQRT  1  N)  FDIV 

12 

13 

14 

NEXT 

10 
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arrived!  Of  course  I  straightaway  photo¬ 
copied  the  bank  cheque  duplicate  and 
sent  it  off  with  an  impassioned  plea. 

Now  (fear  and  trembling)  I  have  been 
told  my  subscription  has  expired  because 
the  cheque  was  not  received.  Bless  my 
chips,  what  will  I  do?  I  know  it  cannot  be 
a  computer  error  because  we  never  err. 
To  make  matters  worse,  my  bank  tells  me 
it  will  be  several  weeks  before  they  can 
find  out  whether  the  bank  cheque  was 
banked  at  the  other  end. 

Please,  Doctor  Dobbs,  help  a  poor 
deprived  little  processor  whose  last  shot 
of  DDJ  was  November  1982!  Please  scan 
your  files  to  make  sure  whether  my 
cheque  has  arrived.  If  my  bank  tells  me 
the  cheque  is  lost,  1  will  send  another  as 
fast  as  I  can. 

Yours  faithfully, 

(signed  for  Neil’s  computer  by) 

Dr.  Neil  Trezise 
Wild  Dog  Creek  Road 
St.  Andrews 
Victoria  9761 
Australia 

Ed.  Note:  Those  of  you  who  have  experi¬ 
enced  similar  problems,  please  bear  with 
us.  During  our  recent  change  of  data 
services,  a  number  of  our  sheep  became 
separated  from  the  fold.  We  are  working 
hard  to  get  this  corrected,  but  unfortu¬ 
nately  these  things  take  a  bit  of  time. 
Sorry  for  the  inconvenience.  Just  let  us 
know  ( most  of  you  already  have)  and  we 
will  make  the  correction. 


Standard  Deviation 

Hi  guys, 

Good  to  see  that  C  compiler  is  pro¬ 
gressing;  nothing  better  than  a  good  free 
software.  I’d  like  to  say  a  few  things 
about  C  pertaining  to  portability  (a  very 
important  issue). 

I’ve  been  seeing  more  and  more  C 
code  that  does  not  follow  the  guidelines 
published  by  Kernighan  &  Ritchie  (The  C 
Programming  Language).  That’s  a  real  no- 
no.  If  everyone  adheres  to  those  guide¬ 
lines  with  care,  C  will  remain  a  very  por¬ 
table  language.  J.  E.  Hendrix  is  guilty  of 
the  crime  himself  in  his  December  article. 
Since  publication  of  the  compiler  imple¬ 
mentation  and  its  libraries  is  a  restatement 
of  the  standard,  it  should  be  done  with 
careful  attention  to  detail. 

Hendrix  describes  several  functions 
in  his  auxiliary  library  which  do  not  main¬ 
tain  the  spirit  of  the  K  &  R  teachings  (the 
C  bible  and  de  facto  definition).  His  dtoi, 
decimal  to  integer,  conversion  function 
sounds  almost  the  same  as  K  &  R’s  atoi 
(ASCII  to  integer).  Doesn’t  matter  which 
name  sounds  better  —  atoi  is  the  standard. 
Also  atoi  only  requires  one  parameter; 
dtoi  unnecessarily  requires  two  (as  do 
Hendrix’s  utoi  and  xtoi).  Also  discordant 
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with  K  &  R’s  atoi  function,  Mr.  Hendrix’s 
itou  and  itox  also  require  one  more  pa¬ 
rameter  than  they  should.  The  string  size 
parameter  is  useful  but,  probably  more 
often  than  not,  not  necessary.  Perhaps 
these  functions  should  be  retained,  given 
names  to  denote  their  special  ability,  and 
not  published  as  the  main  functions  of 
their  type  in  a  “standard”  library. 

I  consider  the  loose  interpretation  of 
the  C  standard  as  it  pertains  to  its  libraries 
a  major  problem  for  its  future  portability. 
I’ve  tried  several  of  the  compilers  availa¬ 
ble  commercially  and  found  them  all  to 
have  problems  in  this  area. 

Both  the  BDS-C  and  the  Supersoft  C 
compilers  have  non-standard  fopen  func¬ 
tions.  That’s  one  function  they  should 
know  enough  to  leave  alone.  BDS  doesn’t 
implement  the  mode  feature  at  all,  and 
requires  a  pointer  to  a  buffer  be  passed  to 
it  (why?).  Supersoft  simply  adds  an  addi¬ 
tional  argument  allowing  you  to  specify 
your  buffer  size.  Handy  perhaps,  but  non¬ 
standard!  Why  not  make  it  an  additional 
function  by  a  different  name  if  you  need 
the  “enhancement.”  Ah,  and  what  about 
the  Cadillac  -  Whitesmith’s?  It  too  re¬ 
quires  an  additional  argument  to  specify 
that  the  buffer  address  be  passed  to  its 
fopen.  But  that’s  just  the  beginning  for 
Whitesmith’s. 

Their  enhancements  (read  “incompat¬ 
ibilities”)  are  legion.  Believe  it  or  not, 
they  don’t  even  have  a  printf  function! 
Or  a  scanf.  They  have  putfmt  and  getfmt 
instead.  They  are  slightly  more  flexible, 
and  don’t  use  the  old  standard  names 
which  is  good,  but  why  no  printf  and 
scanf?  Whitesmith’s  list  of  small  “enhance¬ 
ments”  goes  on  and  on:  strcpy  is  called 
cpystr,  strcmp  is  called  cmpstr,  atoi  is 
called  btoi  (buffer  to  int),  itoa  is  called 
itob,  etc.  My  pessimistic  side  says  they  do 
this  to  lock  you  in  to  their  family  of  C 
compilers  (8080,  PDP- 1 1,  68000,  etc.). 

Come  on  guys,  it’s  a  great  language; 
don’t  muck  it  up. 

Anyone  even  halfway  serious  about 
using  C  and  perhaps  budding  his  own  ex¬ 
tended  library  (that’s  what  it’s  all  about) 
should  read  the  K  &  R  book  from  cover 
to  cover  at  least  twice,  and  pay  close  at¬ 
tention  to  the  style  the  fathers  of  C  have 
developed  and  to  their  many  good  exam¬ 
ples.  Their’s  is  only  one  way  of  doing  it. 
But  it’s  a  good  way,  and  it’s  the  standard. 

Not  to  detract  from  the  very  impor¬ 
tant  C  problem,  I’d  like  to  make  a  note  in 
reference  to  the  “Interrupts  and  CP/M” 
article.  Circular  or  ring  buffers,  as  they’re 
called,  are  very  natural  with  most  proces¬ 
sors,  and  very  handy  as  the  article  shows. 

I  think  Mr.  Bromberger  may  have  missed 
the  point  that  many  things  in  the  com¬ 
puter  world  are  naturally  circular.  As  an 
example,  his  code  to  keep  the  buffer 
pointer  within  the  limits  of  the  buffer: 


inr 

cpi 

jc 

mvi 

inti : 

can  easily  be  replaced  with  the  following 
code  which  is  smaller  and,  I  think,  more 
indicative  of  the  buffer’s  circularity. 

inr  a 
ani  7fh 

inti : 

This  requires  that  the  buffer  size  be  an 
even  power  of  two,  and  the  mask  (7fh  in 
the  example)  be  one  less  than  the  buffer 
size. 

I’d  also  like  to  mention  that  I  feel 
that  little  flap  with  the  JRT  people  is  a 
good  reaffirmation  of  DDJ’s  separation  of 
editorial  and  advertising  policies.  Too  bad 
for  JRT,  they  really  did  us  all  a  service  by 
starting  the  $29.95  movement. 

Thanks  for  a  great  magazine,  and  to 
these  authors  in  particular  for  some  very 
accessible  and  useful  information. 


Sincerely, 

Richard  Foulk 
Pegasus  Software 
P.O.  Box  10J 
Honolulu,  HI  96816 

What’s  the  Holdup? 

Dear  Editor: 

JRT  Pascal  seems  to  be  a  current 
topic  of  interest  among  owners  of  micro 
computers.  There  have  been  several  let¬ 
ters  published  reporting  problems  with 
the  $29.95  Pascal  system.  Maybe  this  will 
be  a  new  activity  to  be  engaged  in.  I  am 
sure  that  the  problems  that  the  owners 
have  found  with  JRT  Pascal  are  real.  If 
JRT  Systems  is  not  going  to  solve  these 
problems,  I  feel  certain  that  the  readers 
of  Dr.  Dobb’s  Journal  will  soon  be  re¬ 
porting  their  solutions.  Since  the  JRT 
System  is  priced  within  the  reach  of 
every  computer  owner,  there  will  be 
many  working  on  meeting  the  new  chal¬ 
lenge. 

I  have  a  problem  that  is  not  new  with 
those  of  us  who  order  by  mail.  I  had  my 
order  processed  on  September  22,  1982 
by  JRT  Systems.  I  have  not  received  my 
JRT  Pascal  as  yet.  Several  letters  to  JRT 
Systems  have  gone  unanswered.  I  hope 
that  my  program  arrives  soon,  and  then  I 
can  start  finding  if  JRT  Pascal  is  good  or 
BAD. 

Sincerely, 

Donald  M.  Dealy 
23 1  Washington  St. 

S.  Attleboro,  M  A  02703 


Ed  Note:  The ^  preceding  letter  was  not 
the  first  that  we  have  received  of  its  kind. 

(Continued  on  page  90) 


11 


16-BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


Cromemco’s  Dual  CPU 

One  of  the  most  pleasant  fringe  bene¬ 
fits  of  starting  up  a  software  house  is  that 
it  gives  one  the  opportunity  to  buy  all 
sorts  of  beautiful  new  hardware  for  “Re¬ 
search  and  Development.”  When  Cro- 
memco  announced  their  combination 
Z-80  and  68000  “DPU”  board  early  this 
year,  I  was  fascinated  but  wary.  The 
board  seemed  as  though  it  potentially 
could  give  the  same  impetus  to  the  68000 
among  personal  computer  users  as  the 
Godbout  Dual  CPU  board  gave  the  8088: 
providing  a  safe,  known  development 
environment  to  fall  back  on  (Z-80  and 
CP/M-80),  while  giving  ready  access  to 
the  power  of  the  68000  microprocessor. 
However,  I  was  a  bit  skeptical  because 
most  of  Cromemco’s  boards  in  the  past 
have  not  completely  followed  the  S-100 
bus  standard,  and  were  difficult  to  mix 
and  match  with  components  produced  by 
other  vendors.  In  addition,  Cromemco’s 
software  is  expensive  and  incompatible 
with  standard  CP/M  application  pack¬ 
ages.  Of  course,  being  a  computer  junkie, 
1  ordered  the  board  anyway. 

About  three  months  after  1  put  down 
a  deposit,  the  board  finally  arrived  and 
immediately  got  stuck  on  the  shelf  for 
another  two  months  due  to  the  pressure 
of  other  work.  Finally,  during  the  Decem¬ 
ber  lull,  I  found  time  to  drag  the  DPU  out 
and  look  it  over.  The  component  is  built 
on  a  typical  S-100,  silk-screened,  multi¬ 
layer  printed  circuit  board,  and  displays 
the  usual  solid  Cromemco  design  and  con¬ 
struction.  It  contains  about  sixty  integrat¬ 
ed  circuits  including  the  familiar  looking 
Z-80  and  the  monstrous  looking  64-pin 
68000.  In  a  departure  from  Cromemco’s 
previous  practice,  all  components  except 
the  two  microprocessors  and  three  other 
support  ICs  are  wave  soldered  directly  to 
the  board  instead  of  being  mounted  on 
sockets.  The  board  is  designated  as  “Revi¬ 
sion  E”  in  the  silk -screened  legend,  but  it 
still  has  no  less  than  eight  little  green 
wires  snaking  their  way  around  -  this 
leads  one  to  believe  that  the  design  of  this 
board  is  not  too  stable  yet. 

The  DPU  board  automatically  starts 
up  in  the  Z-80  mode  of  operation.  When 
a  1  is  output  to  port  0FFH,  the  DPU 
switches  to  the  68000  mode.  The  first 
time  the  68000  is  used,  it  obtains  its 
stack  pointer  from  location  0  and  its  pro¬ 
gram  counter  from  location  4.  To  give 
control  back  to  the  Z-80,  the  68000 
must  write  a  zero  to  location  0FFFFFFH 


(its  I/O  is  memory  mapped).  Subsequent¬ 
ly,  when  either  processor  resumes  execu¬ 
tion,  the  contents  of  its  registers  and  in¬ 
struction  pointer  are  unchanged  from  the 
previous  invocation.  Since  there  is  no  di¬ 
rect  communciation  between  the  registers 
of  the  two  microprocessors,  information 
must  be  passed  back  and  forth  by  tempo¬ 
rarily  saving  it  in  memory.  Listing  1 
shows  how  to  switch  between  the  two 
microprocessors  under  software  control. 

I  can  guess  what  you’re  thinking  if 
you’ve  read  this  far.  In  these  times  of 
economic  unease,  few  of  us  can  afford  to 
junk  our  8 -bit  systems  and  shell  out  sev¬ 
eral  thousand  dollars  for  a  complete  com¬ 
plement  of  Cromemco  boards  including 
memory  and  disk  controller  in  order  to 
get  started  with  a  workable  68 000  system. 
But  I  have  good  news  for  you.  I  was  tipped 
off  by  a  friend  that  the  Dual  CPU  board 
was  “more  S-100  compatible”  than  pre¬ 
vious  Cromemco  products.  In  a  moment 
of  rashness,  I  set  the  jump-on-restart  ad¬ 
dress  for  the  Z-80  to  0000  by  cutting  two 
jumpers,  dropped  the  DPU  board  into  my 
Compu-Pro  Z-80  system,  and  turned  on 
the  power.  The  system  booted  up  and  ran 
perfectly! 

This  opens  up  enormous  possibilities 
'for  experimentation  with  the  68000.  You 
can  do  all  of  your  software  development 
with  a  familiar  CP/M-80  support  struc¬ 
ture  for  disk  and  terminal^  I/O.  When 
CP/M- 68 K  becomes  available,  you  can 
write  your  initial  BIOS  and  cold  boot 
loader  under  CP/M-80,  just  as  many  of 
you  did  when  the  Godbout  8085/8088 
CPU  board  was  first  released. 


By  the  way,  you  will  find  68000  As¬ 
sembly  Language  Programming  by  Gerry 
Kane  et  al.  to  be  an  extremely  useful  re¬ 
ference  work  as  you  are  getting  started. 
This  book  is  devoted  entirely  to  describ¬ 
ing  the  instruction  set  from  a  program¬ 
mer’s  point  of  view  and  is  filled  with 
helpful  examples;  it  does  not  waste  any 
space  describing  the  hardware  —  for  this 
you  can  refer  to  the  manufacturer’s  liter¬ 
ature. 

I  should  note  in  passing  that  Compu- 
Pro  has  also  started  delivering  their  68000 
CPU.  It  costs  only  $625  in  contrast  to  the 
$1000  for  the  Cromemco  board; however, 
it  doesn’t  have  the  advantage  of  the  on¬ 
board  Z-80.  Compu-Pro  is  also  selling  a 
stand-alone  68000  Forth  system  for 
$200,  but  is  not  yet  delivering  the  Digital 
Research  operating  system. 


More  on  Memory  Tests 

Some  readers  will  recall  that  when  I 
reviewed  the  Microsoft  RAMCARD  for 
the  IBM  Personal  Computer,  I  had  some 
critical  things  to  say  about  the  memory 
test  program  that  came  with  it.  At  the 
time,  I  was  just  a  bit  disgusted  with  the 
program’s  style  of  interaction  with  the 
operator  but  had  no  reason  to  find  fault 
with  the  actual  usefulness  of  the  program. 

I  must  report  that  the  program  has  a 
much  more  serious  defect  than  I  imagined : 
if  the  board  it  is  testing  has  read  errors 
causing  parity  errors,  the  test  program 
crashes  completely!  Instead  of  getting  the 
dandy  display  of  the  error  type  and  loca¬ 
tion  as  the  manual  specifies,  the  parity 


Listing  1. 

Switching  between  the  Z-80  and  the  68000  on  Cromemco’s  DPU  board. 
;  switching  on  the  68000 


Id 

hi ,  init 

;move  initial  values 

Id 

de,  0 

; f or  stack  pointer  and 

Id 

be,  8 

;program  counter  into 

ldir 

; locations  0  and  4 

Id 

a ,  1 

;now  turn  on  the  68000 

out 

0ffh,a 

;  switching  on  the. Z-80 

;  (i/o  ports  are  memory  mapped  in  the  top) 
;  (64  k  of  the  address  space  on  the  68000) 

move.b  #0,0ffffffh 
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error  causes  a  hardware  interrupt  forcing 
transfer  to  the  ROM  BIOS,  the  message 
“PARITY  ERROR2”  is  displayed  on  the 
screen,  and  the  system  goes  dead.  Appar¬ 
ently  the  test  program  does  not  reset  the 
interrupt  transfer  vector  so  that  it  can 
intercept  these  events  and  perform  the 
appropriate  error  analysis. 

Regarding  8086/88 
Segment  Registers 

The  Intel  8086/88  documentation  is 
rather  vague  about  the  use  of  default  seg¬ 
ment  registers  in  the  various  indirect 
addressing  modes.  The  iAPX  86,88  User’s 
Manual  states  on  page  2-12  that  “most 
variables  (memory  operands)  are  assumed 
to  reside  in  the  current  data  segment,  al¬ 
though  a  program  can  instruct  the  Bus 
Interface  Unit  to  access  a  variable  in  one 
of  the  other  currently  addressable  seg¬ 
ments  .  .  .  .” 

Leo  Scanlon,  the  author  of  a  book 
on  8088  assembly-language  programming 
(which  is  in  press  at  the  Robert  J.  Brady 
Co.),  has  written  to  point  out  a  surprising 
exception  to  this  rule.  The  base  indexed 
addressing  modes  [BP+SI]  or  [BP+DI], 
which  I  had  always  assumed  were  used  to 
extract  data  from  multi-dimensional  data 
arrays,  do  not  use  DS  (Data  Segment 
register)  as  the  default  but  rather  form 
their  address  in  combination  with  the  SS 
(Stack  Segment  register).  Teleologically, 
this  is  a  bit  unexpected,  but  Leo  proved  it 
experimentally  with  the  program  in  List¬ 
ing  2.  Table  1  is  derived  from  a  similar 
table  in  Leo’s  new  book  and  is  reprinted 
with  his  permission  as  an  aid  to  DDJ 
readers. 


IBM  Low  Resolution 
Graphics  Revisited 

In  an  earlier  column  I  printed  a  BASIC 
listing  which  demonstrated  how  to  initial¬ 
ize  and  use  the  low  resolution  color 
graphics  mode  on  the  IBM  Personal  Com¬ 
puter,  allowing  the  display  of  sixteen 
color  pixels  with  a  resolution  of  160  by 
100.  James  Murphy,  of  Madison,  Wiscon¬ 
sin,  has  kindly  sent  in  a  set  of  Forth  rou¬ 
tines  to  plot  points  in  the  lo-res  mode 
(see  Listing  3);  these  execute  about 
twenty  times  faster  than  the  original 
BASIC  version  even  though  they  are  writ¬ 
ten  in  high-level  code. 

In  Screen  #75  of  the  listing,  the 
definitions  “TR”  and  “CRT_LRC_INIT” 
take  care  of  setting  up  the  video  control¬ 
ler  chip’s  various  registers.  “CLEAR_- 
BUFF”  initializes  the  video  memory  map 
with  the  required  values  so  that  each  pixel 
will  be  displayed  as  a  solid  block  of  color. 
“LRCG”  (mnemonic  for  Low  Resolution 
Color  Graphics)  uses  the  previously  de¬ 
fined  words  to  initialize  the  display  and 
prepare  for  plotting.  In  Screen  #76, 
“!DOT”  (Store  Dot)  accepts  an  address 
and  a  color  and  sets  the  appropriate  pixel 
in  the  memory  map.  X  must  be  in  the 
range  0-159  and  Y  in  the  range  0-99, 
with  (X,Y)  =  (0,0)  being  the  upper  left 
corner  of  the  screen.  Finally,  Screen  #77 
contains  a  nice  little  demonstration  pro¬ 
gram  which  draws  a  test  pattern  of  nested 
squares  in  different  colors. 

Readers  who  wish  to  extend  the  low 
resolution  graphics  capability  even  fur¬ 
ther  can  refer  to  the  Forth  line  drawing 
routine  which  was  printed  in  the  July 
1982  issue  of  DDJ. 


Addressing 

Operand 

Segment 

Mode 

Format 

Register 

Register 

reg 

none 

Immediate 

data 

none 

Direct 

disp 

DS 

label 

DS 

Register 

[BX] 

DS 

indirect 

1  BP  1 

SS 

(Dll 

DS* 

[SI] 

DS 

Base 

[  BX+displ 

DS 

relative 

[  BP+disp  1 

SS 

Direct 

[  Dl+disp] 

DS 

indexed 

[SI+disp] 

DS 

Base 

[  BX+SI+disp] 

DS 

indexed 

[  BX+DI+disp] 

DS 

[  BP+SI+disp] 

SS 

[  BP+DI+disp] 

SS 

*In  string  instructions,  the  destination  ad¬ 
dress  is  formed  by  the  combination  of  D1 
and  ES,  and  the  ES  register  cannot  be  over- 
overridden. 

Notes: 

1.  “disp”  is  optional  for  base  indexed 
addressing. 

2.  “reg”  can  be  any  8-  or  16 -bit  register, 
except  IP. 

3.  “data”  can  be  an  8-  or  16 -bit  constant 
value. 

4.  “disp”  can  be  an  8-  or  16-bit  signed  dis¬ 
placement. 

Table  1 . 

8088  addressing  modes 
and  segment  register  defaults. 


Listing  2. 

Leo  Scanlon’s  program  to  determine  the  default  segment 

registers  for  base  indexed  addressing  on  the  Intel  8086/88. 

STACK 

SEGMENT 

PARA  STACK  'STACK' 

DB 

100  DUP  ( 0FFH ) 

STACK 

ENDS 

DATA 

SEGMENT 

PARA  'DATA' 

DB 

0  ABH 

DATA 

ENDS 

CODE 

SEGMENT 

PARA  'CODE' 

PROG 

PROC 

FAR 

ASSUME 

CS : CODE , DS : DATA  f SS: STACK 

MOV 

AX , DATA  ;initialize  DS 

MOV 

DS,  AX 

SUB 

BP, BP  ;clear  the 

SUB 

SI, SI  ;addressing  regs. 

SUB 

D I , DI 

MOV 

DL, [BP+SI]  ; read  memory  with 

MOV 

DH, [BP+DI]  ;based  indexed  addr. 

RET 

PROG 

ENDP 

CODE 

ENDS 

END 

CODE 

(Listing  3  on  page  18) 
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Listing  3. 

Laboratory  Microsystems  PC/ Forth. 


Screen  #  75 

O  (  Lo  Res  Col  or  Graphics 
1  FORTH  DEFINITIONS  HEX 


12/27/82  ) 


(  initialize  video  controller  chip  ) 

:  TR  3D4  PC!  3D5  PC!  ; 

:  CRT_LRC_ I N I T  9  3D8  PC!  07F  4  TR  64  6  TR  70  7  TR  1  9  Tl 

<  initialize  video  memory  map  tor  low  res  graphics  ) 

:  CLEARBUFF  4000  0  DO  ODE  B800  I  ! L  2  +LOOP  ; 

<  set  operating  mode  tor  low  resolution  color  graphics  ) 

:  LRCG  2  MODE  CRT_LRC_INIT  CLEAR_BUFF  ; 


12  — > 
13 


Screen  #  76 

O  (  Lo  Res  Color  Graphics  12/27/82  ) 

1 

2  (  plot  point  in  low  res  graphics:  x  y  color  -  ) 

3  :  ! DOT  ROT  DUP  1  AND 

4  IF  ROT  OAO  *  +  B800  SWAP  2DUP  C3L 

5  OFO  AND  >R  ROT  R>  OR  ROT  ROT  C!L 

6  ELSE  1  OR  SWAP  10  *  SWAP  ROT  OAO  *  + 

7  B800  SWAP  2DUP  C3L  OF  AND 

8  >R  ROT  R>  OR  ROT  ROT  C!L 

9  THEN  ; 

10 

11  DECIMAL 


Screen 


(  Lo  Res  Color  Graphics  demonstrat i on 
3  VARIABLE  COLOR 

O  VARIABLE  CSEQ  2  ,  4  ,  6  ,  8  ,  1 

1  ,  3  ,  5  ,  7  ,  9  ,  1 


12/27/82  ) 


:  SQUARE 


:  DEMO 


2  ,  4  ,  6  ,  8  ,  10  ,  12  ,  14  , 

1  ,  3  ,  5  ,  7  ,  9  ,  11  ,  13  ,  15  , 

DUP  80  +  OVER  80  SWAP  - 

3  PICK  DUP  50  +  50  ROT  -  SWAP  1+  SWAP 
DO  DUP  I  COLOR  3  ! DOT  OVER  I  COLOR 
LOOP  2DROP  DUP  50  +  OVER  50  SWAP  - 
3  PICK  DUP  80  +  80  ROT  -  SWAP  1+  SWAP 


LOOP 


DUP  I  SWAP  COLOR  3  ! DOT 
OVER  I  SWAP  COLOR  3  ! DOT 
2DROP  DROP  ; 


LRCG  50  0 


DO 

LOOP 


I  15  AND 
KEY  DROP 


?*  CSEQ 
>  MODE  ; 


COLOR 


SQUARE 
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AUGUSTA,  Part  II 

The  Augusta  P-Code  Interpreter 


Part  1  of  this  four- part  series  de¬ 
scribed  the  Augusta  language.  This 
month’s  article  continues  with  a  de¬ 
scription  of  the  p-codes  and  the  p-code 
interpreter  that  executes  Augusta  pro¬ 
grams. 

Stack  Machines 

The  Augusta  compiler  translates 
source  statements  into  code  for  a  hypo¬ 
thetical  “pseudo-machine”  based  on  the 
use  of  stacks.  Stacks  provide  a  natural 
representation  for  arithmetic  expressions 
and  for  implementing  nested  procedure 
calls  and  local  data  definitions. 

Owners  of  Reverse  Polish  Notation 
(RPN)  calculators  are  already  familiar 
with  stacks  and  their  use  for  evaluating 
expressions.  The  basic  operations  per¬ 
formed  on  the  stack  are  push  and  pop,  to 
add  and  to  remove  data  to  and  from  the 
stack,  respectively. 

A  stack  is  often  compared  to  a  spring 
operated  stack  of  plates  in  a  cafeteria.  A 
new  plate  is  added  by  pushing  it  on  to  the 
top.  When  a  plate  is  removed,  the  whole 
stack  pops  upwards.  For  example,  if  we 
push  both  13  and  10,  the  stack  looks  like 

10 

13 

Then,  we  can  add  them  together  to  give 
23 

If  we  translated  these  steps  to  an  assembly¬ 
like  language,  we  might  write 

PUSH  13 
PUSH  10 
ADD 

Complicated  expressions  like  5*(3  +  7)  are 
coded  as 

PUSH  5 
PUSH  3 
PUSH  7 

ADD  ; Add  3  +  7 
MULT  ;  Multiply  result  by  5 

With  a  few  more  instructions,  the  stack 
becomes  a  general  purpose  expression 
evaluator.  For  example,  to  perform  the 
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assignment,  X:=10+13  on  a  stack  ma¬ 
chine,  the  following  sequence  of  instruc¬ 
tions  might  be  executed 

PUSH  address  of  X 

;  Put  the  memory  address 
;  of  X  on  stack 

PUSH  10 

PUSH  13 

ADD  ;  Compute  10+12, 

;  leaving  23  on  stack 

STORE  ;  Store  top  of  stack  value 

;  into  the  address  con- 
;  tained  in  the  next  word 
;  on  the  stack 

The  Augusta  p-machine  consists  of  about 
80  instructions  (see  Table  1 )  to  manipulate 
the  stack  and  perform  other  functions 
such  as  conditional  testing,  branching, 
procedure  calls  and  returns. 

P-Machine  Overview 

The  p-machine  is  a  16-bit  stack- 
oriented  hypothetical  computer.  It  has  a 
code  pointer  register  CP  that  contains  the 


byte  address  of  the  next  instruction  to 
execute,  and  a  stack  pointer  SP  that 
points  to  the  top  of  the  stack.  In  addition, 
the  global  frame  pointer  OF  and  the  local 
frame  pointer  LF  are  used  to  speed  up 
references  to  global  and  local  variables, 
respectively. 

Registers  SB  (Stack  Base)  and  CB 
(Code  Base)  are  of  use  when  debugging 
programs  and  point  to  the  bottom  of  the 
stack,  and  to  the  first  byte  of  code  for 
the  currently  executing  procedure.  CS 
(Code  Segment)  points  to  the  address  of 
the  first  byte  of  code.  The  number  of  the 
procedure  that  is  executing  is  stored  in 
the  PN  register  (the  first  “PROCEDURE” 
seen  in  a  program  becomes  procedure  1, 
the  second  “PROCEDURE”  statement 
becomes  procedure  2,  and  so  on). 

Before  a  program  can  be  run,  it  must 
be  loaded  into  memory.  One  more  regis¬ 
ter,  PT,  contains  the  address  of  the  proce¬ 
dure  table.  The  procedure  table  contains 
a  7-byte  entry  for  each  procedure  in  the 
program  and  includes  (1)  the  address  in 
memory  of  the  procedure’s  code,  (2)  the 


Corrections  to  Augusta,  Part  I 


Several  last  minute  editing  changes 
were  made  by  both  the  author  and  the 
editors  at  Dr.  Dobb’s  in  order  to 
shorten  the  length  of  Part  1.  Unfortu¬ 
nately,  a  few  incorrect  and  misleading 
statements  crept  into  the  text. 

The  Augusta  compiler  is  written 
in  Microsoft  BASIC,  and  hence,  can  be 
run  on  systems  other  than  a  standard 
CP/M  system.  However,  compiled  pro¬ 
grams  can  only  be  executed  by  using 
the  p-code  interpreter,  a  program  that 
currently  runs  only  on  Z-80 -based 
CP/M  systems.  While  I  do  hope  to  pro¬ 
duce  an  MS-DOS  version,  it  was  prema¬ 
ture  for  the  editor’s  note  to  announce 
that  such  a  version  will  be  available 
shortly. 

Originally,  Part  2  of  the  series  de¬ 
scribed  a  BASIC  language  implementa¬ 
tion  of  the  p-code  interpreter.  But 
that  description  was  removed  and 
some  of  the  comments  in  Part  1  no 
longer  apply.  For  example,  the  BASIC 
p-code  interpreter  implemented  virtual 
memory  but  the  assembly-coded  ver¬ 
sion  of  the  interpreter  does  not. 

The  variable  declaration 


defines  S  as  a  string  of  up  to  80  bytes 
(not  128,  as  shown  in  Part  1).  A  differ¬ 
ent  length  is  specified  by  writing 

S  :  STRING(200); 

which  gives  S  a  length  of  200  bytes. 
Maximum  string  length  is  254  bytes. 

Part  1,  Table  1  summarized  only  a 
few  of  the  available  “built-in”  proce¬ 
dures  and  functions.  With  nearly  40 
procedures,  Augusta  provides  an  Ada- 
like  file  system,  printer  and  serial  port 
I/O,  string  searching,  MOVELEFT, 
MOVERIGHT,  and  a  very  limited  dy¬ 
namic  memory  allocation  scheme. 

To  support  file  access,  a  fifth  pre¬ 
defined  type  is  used,  as 

F  :  IN_OUT _FILE; 

which  defines  F  as  a  file  access  varia¬ 
ble.  File  variables  may  be  grouped  in 
arrays  and  passed  as  OUT  procedure 
parameters. 

The  syntax  diagrams  contained 
three  minor  errors.  Corrections  are 
shown  in  Figure  1  (opposite).  Proce¬ 
dures  and  functions  are  not  required 
to  have  parameter  lists  as  was  implied 
by  the  original  diagrams,  and  an  ELSE 


S  :  STRING; 


may  not  follow  an  ELSEIF. 
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Changes  to  SEQ  OF  STMTS 


PARAM  LIST 


Changes  to  PRIMARY 


(FUNCTION  CALL) 

dentfN 

PARAM 

LIST 

[REPLACES  (FUNCTION)  ON  ORIGINAL] 

Figure  1. 

Corrected  Syntax  Diagrams  for  the  Augusta  Language 


number  of  bytes  of  parameter  variables, 
(3)  the  amount  of  memory  required  for 
local  variables,  and  (4)  the  “lexical  level” 
of  the  procedure. 

All  procedure  calls  are  made  through 
the  procedure  table.  The  instruction 
CGP  5,  for  example,  means  to  call  proce¬ 
dure  5.  The  location  of  procedure  5  and 
how  much  memory  to  allocate  for  its 
local  variables  are  fetched  from  entry  5 
in  the  procedure  table. 


The  P-Code  Instructions 

The  entire  group  of  instructions  is  di¬ 
vided  into  several  smaller  groups  consisting 
of  (1)  “load”  and  “store”  instructions, 
(2)  string  assignments,  (3)  logical  opera¬ 
tions,  (4)  integer  arithmetic  operations, 
(5)  integer  comparisons,  (6)  string  com¬ 
parisons,  (7)  jump  instructions,  and  (8) 
procedure  calls  (see  Table  1,  pages  3  1-33). 

A  simple  operation  is  to  load  a  con¬ 
stant  on  to  the  stack.  The  LDCI  or  “Load 
Constant  Integer”  opcode  is  a  single  byte 
long,  followed  by  a  one-word  (16-bit) 
value.  When  the  p-code  interpreter  is  ex¬ 
ecuting  instructions,  CP  always  points  to 
the  next  byte  of  the  program  code.  For 
LDCI,  the  p-machine  reads  the  instruc¬ 
tion  and  .decodes  the  opcode  byte.  Then 
it  jumps  to  the  appropriate  LDCI'  sub¬ 
routine  to  load  the  constant.  The  actual 
constant  is  stored  in  the  two  bytes  fol¬ 
lowing  the  instruction,  as  shown  here: 


LDCI 


0 


17 


CP  points  to  this 
instruction 

the  operand  follows  in 
in  two  bytes 


After  the  LDCI  opcode  is  read,  CP  is 
incremented  to  point  to  the  first  byte  of 
the  constant.  The  LDCI  subroutine  then 
reads  the  16 -bit  integer  and  pushes  it  on 
the  stack.  A  push  is  performed  by  writing 
the  word  into  the  memory  location 
pointed  to  by  SP,  and  then  incrementing 
SP  by  two  (since  one  word  occupies  two 
bytes  and  SP  always  points  to  a  word). 
CP  is  incremented  so  that  it  points  to  just 
past  the  second  byte  of  the  constant, 
which  is  the  next  instruction. 

Four  data  types  are  recognized  by 
the  p-machine:  (1)  8-bit  bytes,  (2)  16-bit 
integers,  (3)  fixed-length  strings,  and  (4) 
boolean  values.  An  integer  takes  two 
bytes  and  represents  numbers  in  the  range 
-32768  to  32767.  A  string  uses  a  fixed 
amount  of  memory  determined  from  its 
declaration  in  the  Augusta  program,  plus 
one  byte  to  hold  the  current  length  of  the 
string.  For  example,  if  S  is  a  string  of  up 
to  80  characters  in  length,  then  81  bytes 
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of  storage  are  reserved.  The  first  byte 
holds  the  length  as  illustrated  here: 


|Len|  |  !  I  ...  |  i  | 


123  79  80 

For  example,  the  string  “Alphabet”  would 
be  stored  in  memory  as 


i8jAjl!pjhjajbje!t|... 


A  boolean  TRUE  is  any  non-zero  word 
while  FALSE  is  a  word  containing  zero. 

A  variety  of  instructions  are  used  to 
load  the  values  or  addresses  of  both  glo¬ 
bal  and  local  variables.  Several  variations 
on  these  instructions  are  provided  to  ac¬ 
cess  “intermediate  level”  variables  (these 
occur  when  procedures  are  defined  inside 
of  procedures  that  are  defined  inside  of 
procedures,  ad  infinitum)  and  special 
“short”  forms  that  reduce  the  size  of  the 
compiled  programs. 

A  single  instruction  “STO”  writes 
the  word  on  the  top  of  the  stack  into  the 
address  contained  in  the  second  word 
from  the  top  of  the  stack. 

Strings  are  never  loaded  on  to  the 
stack.  Instead,  just  a  pointer  to  the  string 
is  loaded.  For  example,  when  the  state¬ 
ment 

S  :=  “STRING”; 

is  compiled,  Augusta  translates  this  to  a 
“Load  Constant  Address”  (LCA)  instruc¬ 
tion,  followed  by  the  string  assignment 
operator  SAS.  The  constant  string 
“STRING”  is  translated  by  Augusta  into 

LCA  6  STRING 
t 

Length  Byte 

When  the  p-machine  encounters  the  LCA 
opcode,  it  pushes  the  address  of  the  length 
byte  on  to  the  stack.  Then  it  sets  CP  to 
point  to  the  first  byte  after  “STRING.” 

Logical  and  arithmetic  instructions 
perform  an  operation  to  the  top  one  or 
two  words  of  the  stack.  For  example, 
ADI  pops  the  top  two  words  from  the 
stack,  adds  them  together  and  then 
pushes  the  result.  Relational  operators, 
like  EQUI,  pop  the  top  words  and  com¬ 
pare  the  values.  If  the  relation  is  true, 
then  a  non-zero  word  is  pushed,  other¬ 
wise  a  zero  is  placed  on  the  stack. 

Stacks  and  Procedure  Calls 

When  a  program  executes  a  proce¬ 
dure  call,  the  computer  uses  a  stack  to 
keep  track  of  the  “return  address.”  Each 
time  that  a  procedure  is  called,  the  return 
address  is  pushed.  If  a  called  procedure, 
in  turn,  calls  another  procedure,  then 
both  return  addresses  are  distinct.  The  re¬ 
turn  address  of  the  most  recently  called 
procedure  is  always  the  topmost  address 
on  the  stack. 

When  a  procedure  finishes,  it  pops  its 
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return  address  from  the  stack  and  resumes 
execution  at  its  calling  point.  As  we’ll  see 
in  a  moment,  the  stack  is  also  used  to 
hold  additional  information.  The  portion 
of  the  stack  that  holds  the  return  address 
is  known  as  the  “frame  mark.”  The  frame 
mark  delineates  each  procedure  from  the 
other  procedures  on  the  stack  and  saves 
the  state  of  the  procedure  that  was  run¬ 
ning  before  the  procedure  call. 


Variable  Allocations 

Augusta  permits  nested  procedure 
definitions.  Each  procedure  can  have  its 
own  local  data.  Space  for  local  variables  is 
allocated  when  the  procedure  is  called. 
When  the  procedure  exits,  all  of  the  space 
used  by  the  local  variables  is  made  free. 

Figure  2  (page  24)  shows  how  a  stack 
machine  allocates  storage  space  for  varia¬ 
bles  defined  in  the  outermost  procedure 
and  for  local  variables  defined  within 
called  procedures.  The  variables  in  the 
outermost  procedure  are  accessible  to  all 
of  the  procedures  that  are  contained 
within  it  and  are  referred  to  as  “global” 
variables.  Global  storage  space  appears  on 
the  bottom  of  the  stack. 

When  a  procedure  is  called,  any 
needed  parameters  are  pushed,  a  frame 
mark  containing  the  return  address  and 
other  information  is  output,  and  the 
stack  pointer  is  incremented  high  enough 
to  leave  space  above  the  frame  mark  for 
local  variables.  When  the  procedure  fin¬ 
ishes  executing,  the  information  from  the 
frame  mark  is  restored,  and  the  stack 
pointer  is  cut  back  to  where  it  was  before 
the  parameters  were  pushed.  In  this  man¬ 
ner,  all  local  storage  space  is  allocated 
dynamically  at  the  time  of  the  procedure 
call,  and  then  disappears  upon  return  to 
the  caller. 

Global  variables  are  referenced  as  an 
offset  from  the  global  frame  mark  at  the 
base  of  the  stack.  For  example,  a  variable 
at  offset  2  is  referenced  with  the  “Load 
Global  Value”  instruction 

LDO  2  ;  Load  Global  instruction 

The  location  of  the  global  frame  is  kept 
in  register  GF.  To  fetch  the  value  at  off¬ 
set  2,  the  p-machine  adds  2  to  GF  which 
computes  the  memory  address  of  the  glo¬ 
bal  memory  word. 

Local  variables  are  referenced  as  an 
offset  from  the  local  frame  mark  so  that 
the  instruction 

LDL  3  ;  Load  Local  instruction 

references  the  data  three  bytes  above  the 
local  frame  mark.  Register  LF  always 
contains  the  address  of  the  currently  ex¬ 
ecuting  frame. 

Parameter  variables  are  also  refer¬ 
enced  with  the  local  data  instructions. 
Since  parameters  are  located  below  the 
frame  mark,  the  local  instruction  uses  a 
negative  offset.  For  example, 


LDL -16  ;  Load  the  value  of 
;  first  parameter 


Handling  Nested  Procedures 

Augusta,  like  Ada  and  Pascal,  allows 
nested  procedure  definitions  as  in  Figure 
3  (page  28).  Procedure  P4,  inside  P3,  can 
reference  variables  in  both  P3  and  P2. 
These  variables  are  neither  “global”  nor 
“local”  to  P4.  Instead,  they  are  “up-level” 
references. 

After  P4  has  been  called,  the  stack  is 
as  shown  in  Figure  3(b).  To  reference 
variable  Y  in  procedure  P3,  the  p-machine 
has  to  refer  to  the  previous  frame  on  the 
stack.  Similarly,  to  reach  variable  X,  the 
p-machine  must  traverse  backwards  two 
frame  marks  to  reach  the  local  data  of 
procedure  P2.  Because  of  up-level  refer¬ 
ences,  the  frame  mark  needs  to  contain 
more  than  just  the  return  address. 

The  return  address  or  “dynamic  link” 
chains  together  the  frame  marks  in  the 
order  that  the  procedures  were  called.  If 
procedure  P4  makes  a  recursive  call  on 
procedure  P3,  P4  cannot  be  the  previous 
frame  for  an  up-level  variable  reference. 
If  it  were,  then  P3  could  up- level  address 
variables  for  a  lower  level  procedure. 
Therefore,  the  dynamic  link  is  insufficient 
for  up-level  addressing.  Instead,  a  static 
link  is  used  to  reflect  the  structure  of  the 
program. 

When  P3  calls  P4,  the  static  link  of 
P4’s  frame  mark  points  to  the  frame  mark 
of  P3.  If  P4  calls  P3,  a  new  frame  is  cre¬ 
ated  for  P3  on  top  of  the  stack.  However, 
P3’s  static  link  is  set  to  point  to  the  frame 
for  P2,  because  P3  is  declared  inside  of 
P2. 

In  addition  to  the  dynamic  and  the 
static  links,  the  frame  mark  also  contains 
the  number  of  bytes  of  parameters,  the 
lexical  nesting  level,  and  the  code  base 
pointer  of  the  current  procedure.  The 
lexical  level  is  the  depth  of  nested  proce¬ 
dure  definitions.  If  P2  is  inside  of  PI,  the 
first  procedure  in  the  program,  then  P2  is 
at  lexical  level  2.  Similarly,  if  P3  isdefined 
inside  of  P2,  then  P3  is  at  lexical  level  3. 


Code  File  and  Memory  Layout 

The  p-code  interpreter  is  contained 
in  a  code  file  named  RUN.  (Note:  An 
alternate  p-code  interpreter  named  DRUN 
contains  a  built-in  debug  utility.  The 
utility  provides  program  tracing,  single- 
step  and  n-step  execution,  and  examining 
and  changing  the  value  of  variables.)  The 
interpreter  reads  the  code  file  into  mem¬ 
ory  and  begins  execution. 

The  code  file  is  organized  into  three 
sections  (see  Figure  4(a),  page  29):  (1)  a 
128-byte  header  block  containing  infor¬ 
mation  about  the  code  file,  (2)  a  1792- 
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byte  procedure  table  containing  space  for 
256  procedures  (entry  256  is  not  used), 
and  (3)  the  p-code  for  each  of  the  pro¬ 
cedures  in  the  program. 

When  the  code  file  is  loaded,  only 
the  used  portion  of  the  procedure  table  is 
read  into  memory.  Obviously,  if  the  pro¬ 
gram  only  contains  ten  procedures,  then 
only  the  first  part  of  the  table  needs  to  be 
read. 

After  the  code  is  loaded,  the  CP  reg¬ 
ister  is  initialized  to  the  first  p-code  in 
procedure  1,  and  the  stack  pointer  is  set 
to  point  to  the  first  word  after  the  p- 
codes.  The  other  registers,  including  GF, 
LF,  and  PT,  are  set  as  needed.  Figure  4(d) 
shows  the  memory  layout  after  a  code 
file  has  been  read  into  memory. 

Augusta  Efficiency 

One  way  to  measure  a  language’s 
efficiency  is  to  run  a  benchmark  test  and 
compare  the  size  of  the  generated  code 
and  its  execution  time  to  that  of  other 
languages.  Listing  1  (page  35)  is  the 
source  code  of  a  simple  prime  number 
generator  based  on  the  sieve  of  Eratos¬ 
thenes.  (Listing  2,  also  on  page  35,  is  the 
disassembly  of  that  same  program’s 
object  code  into  p-codes.)  Table  2  (page 
34)  compares  that  program,  written  in 
Augusta,  to  versions  written  for  several 
other  well-known  compilers  (see  refer¬ 
ences  1  and  2,  below). 


In  the  May  Issue 

The  Augusta  compiler  is  a  one-pass 
recursive  descent  compiler.  As  the  parser 
recognizes  a  language  construct,  it  gener¬ 
ates  the  appropriate  code.  Part  3  provides 
a  general  description  of  recursive-descent 
compilers. 

(Figure  3  on  page  28) 

(Figure  4  on  page  29) 

(Figure  5  on  page  30) 

(Table  1  on  page  31) 

(Table  2  on  page  34) 
(Fistings  1  and  2  on  page  35) 


References  for  Part  2. 
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( 

Figure  2b) 

B 

PROCEDURE  PI  IS 

A 

I  :  INTEGER; 

J  :  INTEGER; 

#  parameters 

dynami c  link 

PROCEDURE  P2  <  X  :  INTEGER  )  IS 

static  link 

A  :  INTEGER; 

B  :  INTEGER; 

Previous  CB 

Previous  CP 

BEGIN 

Previous  PN 

Lex  Level 

END; 

P2’s  X  =  3 

j 

BEGIN 

i 

< —  GF 

P2<3) ; 

END: 

Figure  2. 

Storage  for  variables  is  allocated  on  the  stack,  (b)  is  a  map  of  the  stack  for  the  pro¬ 
gram  shown  at  (a),  after  P2  was  called.  Space  for  I  and  J  is  allocated  at  the  base  of 
the  stack.  When  P2  is  called,  its  single  parameter,  3,  is  pushed  on  the  stack  and 
topped  with  the  frame  mark  for  P2  and  P2’s  local  variables. 
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(Figure  3  a) 


PROCEDURE  PI  IS 
W  s  INTEGER; 

PROCEDURE  P2  IS 
X  :  INTEGER; 

PROCEDURE  P3  IS 
Y  :  INTEGER; 

PROCEDURE  F'4  IS 
Z  :  INTEGER; 
BEGIN 
Z  :=  Y; 

Z  :=  X; 

END;  —  P4 


—  ACCESS  Y  IN  P; 

—  ACCESS  X  IN  p; 


BEGIN 
Ys=l ; 

F'4; 

END;  '  —  P3 

BEGIN 
X:  =2; 

P3; 

END;  —  P2 

BEGIN 

F’2; 

END;  —  F*1 


(Figure  3b) 


■ 

z 

P4  *  s 

Frame 

Mark 

— > 

Y 

P3’s 

Frame 

Mark 

X 

P2's 

Frame 

Mark 

W 

PI'S 

Fr  ame 

Mark 

Static 
Link  to 
Previ ous 
Frame 


Static 
Link  to 
Previous 
Frame 


Figure  3. 

Procedures  can  be  defined  inside  of  other  procedures,  as 
shown  at  (a).  When  P4  references  variable  Y,  the  p-machine 
must  traverse  down  the  stack  to  the  previous  frame  mark  to 
reach  Y.  Similarly,  a  reference  to  X  is  a  reference  to  two 
frames  lower  in  the  stack. 
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Figure  4. 

Detailed  layout  of  an  Augusta  code  file  and  of  memory  after  a  program  has  been  loaded,  (a)  shows  the  code  file  format,  (b) 
and  (c)  detail  the  format  of  the  header  block  and  of  the  proceedure  table,  and  (d)  shows  the  memory  layout  of  a  loaded 
program.  (Continued  on  next  page) 
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Table  1. 

The  Augusta  P-Code  Instruction  Set. 

All  of  the  Augusta  p-code  instructions  are  shown  in  Table  1.  The  number  in  parenthesis  is  the  opcode  value.  A  “b”  following 
the  opcode  indicates  that  there  is  a  one-byte  parameter,  “w,”  “wl,”  and  “w2”  are  16-bit  words.  In  the  descriptions,  TOS  is 
the  word  on  the  top  of  stack,  and  TOS-1  is  the  word  just  below  the  top  of  stack. 

Loads 

and  Stores 

(  1  > 

L  D  C I  w 

Load  Constant  Immediate  Word 

(  V  ) 

LDL  w 

Load  Local  word  at  offset,  w 

(  3  > 

LLA  w  — 

Load  address  of  Local  word  at  offset  w 

(  4  > 

L.DB 

Load  the  byte  pointed  to  by  the  pointer  in  TOS. 

(  5) 

LDO  w 

Load  global  word  at  offset  w 

<  6 ) 

LAO  w 

Load  global  address  at  offset  w 

<  8) 

L  .OD -b  ,  — w  — 

Load  word  up  level  b  static  links  at  offset  w 

<  9 ) 

LDA  b ,  w 

Load  address  up  level,  as  above. 

(.id 

STO 

S  t  o  r  e  i  n  d  i  r  e  c  t  1  0  S  i  n  t  o  a  (d  d  r  e  s  s  i  n  i  U  S  - 1 

(  1 2  > 

SINDO 

Load  indirect  using  the  address  in  TOS 

Short, 

Loads 

( *~j  7 ) 

SLDQ  b 

Short  Load  Global  data  at  offset  b.  b  is  in 

the  r  an ge  0 . . 255 . 

< 58 1 

SLAO  b 

Short.  Load  address  at  global  offset  b„  b  is  in 

t  h  e  r  a  n  cj  e  0 .  .  2 5 5 , 

<  59 ) 

SL..LA  b 

Short.  Load  Local  Address  at  local  offset  b. 

<  60 ) 

SLDL  b 

Short  Load  Local  data  at  local  offset  b. 

(61 ) 

SL  DC  b 

Short  Load  Constant,  in  the  range  0..255. 

< 49 ) 

to  (56)  SLDL 

.0  .  .  SLDL 7 

Single  byte  opcodes  to  Short  Load  Local  Dat a  at 
local  offset  0  through  7. 

( 63 ) 

SL  DC  IM1 

Short  load  negative  1  (—1) 

<64 ) 

to  (79)  SLDCO  .  »  SLDC15 

—  Single  byte  opcodes  to  short,  load  a  constant  in 
the  range  0  to  15. 

Array 

(24) 

1 D  d  e  x  i  n  g  I  n  s  t  r  u  c  t  i  g  n  s 

IND  —  Index  an  integer  array.  TOS— 1  is  the  address 

of  the  base  of  the  array  and  TOS  is  an  index 
into  the?  array.  IND  pops  TOS,  multiplies  it. 

by  2  and  adds  it  to  TOS— 1,  pushing  the  result. 

(Continued  on  page  32) 
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(Table  1  continued  from  page  31) 


(48)  I  X A  b 


I n d e v.  a r r a y .  T h is  is  a  gen e r a  1  i z ed  I N D  o p c o d e „ 
where  b  substitutes  -for  the  "2"  multiplier. 


S  t  r  i  n  g  A  s  s  i  g  n  m  e  n  t  s 
(13)  L  C  A  b  ,  <  C  h  a  r  s  > 

Load  address  of  a  string  constant-  b  is  the 
number  of  bytes  in  the  string  address-  < Chars > 
are  the  characters  in  the?  constant-  Pushes  the 
address  of  the  byte  containing  b  and  increments 
CP  to  point  to  the  next  instruction  following 
<Chars>. 


( 1 4 )  SAS 


String  Assignment-  TOS  is  a  pointer  to  source 
s  t  r  i  n  g  a  n  d  T  0  S  —  1  p  o  i.  rt  t  s  t  o  a  d  e  s  t  i  n  a  t  ion  -  C  o  p  i  e  s 
bytes  from  the  source  string  to  the  destination  string. 


L  o  g  i  c  a  1  0  p  e  r  a  t  g  r  s 

(16)  AND  -  Boolean  AND  of  TOS  and  TOS— 1 


(17)  OR  -  Boolean  OR  of  TOS  and  TOS-1 

(18)  NOT  —  Boolean  complement.  TOS  < —  NOT  TOS 

I  n t. eg er  Ar  i  t h met  i  c  Op er  at  i  on s 


( 19) 

ADI 

-  Add  the  integers  in  TOS 

and  TOS— 

1 . 

( 20 ) 

NS  I 

-  Let  TOS  equal  -TOS. 

(21) 

SB  I 

-  Subtract  integers.  TOS- 

1  minus 

TOS. 

(22) 

MP I 

-  Multiply  integers  in  TOS 

and  TOS 

-1 . 

<  23 ) 

DO  I 

-  Divide  integers,  TOS-1  divided  b 

y  TOS. 

(45) 

NOD  I 

-  TOS-1  MOD  TOS 

(80) 

I NCL  w 

-  Increment  word  at  local 

of  f  set  w 

■ 

(81) 

DECL  w 

-  Decrement  word  at  local 

offset  w 

■ 

I  n  t  e  g  e  r  C  g  m  p_  a  r  i  s  o  n  s 

The  comparions  push  -1  if  the  result  is  true,  or  0 
if  the  comparison  is  false. 


(25) 

EQiJI 

—  Compare 

T  OS 

( 26 ) 

NEQ I 

-  TOS 

<  > 

70S- 1 

(27) 

LEO  I 

-  TOS- 

-1  < 

=  TOS 

(28) 

LES I 

-  TOS- 

-1  < 

TOS 

(29) 

GEO  I 

-  TOS- 

- 1  >; 

=  70S 

(  =  ) 
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( 30 ) 

6TRI 

-  T0S-1  >  TOS 

Str  i  r 

ci  Compari 

sons 

TOS  and  TOS— 1  are?  pointers  to  the  strings 
to  compare.  Pushes  ~T  i  f  the  comparison  is  true 
or  0  if  the  comparison  is  false. 

(31) 

EQUSTR 

-  TOS— 1  =  TOS 

( 32  > 

NEQSTR 

-  TOS— 1  <>  TOS 

(33) 

LEQSTR 

-  TOS— 1  <=  TOS 

( 34 ) 

LESSTR 

-  TOS—  1  <  TOS 

( 35  > 

GEQS 1  R 

-  TOS— 1  >=  TOS 

( 36 ) 

G1 RS 1 K 

-  TOS— 1  >  TOS 

Jump. 

1 0  §  t  r  u  c  t  i.  g  o  s 

All  jumps  are  made  relative  to  the  location  of  the 
instruction . 

( 37 ) 

UJP  w 

-  Unconditional  jump  to  w  bytes  away  from 
current  i nstruct i on . 

<  38 ) 

FJP  w 

-  False  Jump.  Jump  if  TOS  is  0. 

( 39 ) 

X  J  P  w  1 ,  w 

2 ,,  w3 

—  Case  jump  instruction.  See  text  for  description. 

Pr oc edure  Cal  J._ 

s  arid  Returns 

(40) 

CLP  b 

-  Call,  local  procedure  b. 

(41 ) 

CGP  b 

-  Ca 11  global  p r oc ed ur e  b . 

(42) 

CSP  b 

—  Call  system  procedure  b.  System  procedures 
handle  all  input/ou t. p u t „ 

( 4  6 ) 

CIP  b 

—  Call  intermediat e  level  procedure  b . 

(43) 

RET 

—  Return  from  a  procedure. 

( 46 ) 

RNP 

—  Return  from  a  function  by  saving  the  TOS  value? 
setting  SP  back  before  the  parameters  and  frame 
mark  for  the  current  procedure  and  then  restoring 
the  T(I)S  v a lue. 

Mi  seel  1 eneous 
(15)  EOF 

—  End  of  Procedure  mark.  This  opcode  is  never  executed 

but  is  output  to  mark  the  end  of  a  procedure’s  code. 

(End  Table  1 ) 
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IS 


Language 

Compiled 

(bytes) 

Compile/load 

(seconds) 

Execute 

(seconds) 

Pascal  MT+ 

308 

102 

19 

Janus  Ada 

- 

- 

27 

UCSD  Pascal,  Z -80 

282 

14 

239 

UCSD  Pascal,  TRS-80  Mod  11 

282 

60 

274 

Augusta,  Z-80  Osborne  I 

162 

30 

303 

JRT  Pascal  V2.0 

224 

34.5 

383 

Supersoft  Ada 

- 

- 

422 

Pascal/M 

301 

50 

450 

JRT  Pascal 

232 

65 

470 

C  BASIC  2 

- 

26 

484 

Tiny-C  Compiler 

- 

96 

930 

Table  2. 

Comparison  of  Augusta  with  other  languages.  Chart  indicates  compiled  program 
size  and  compilation/load  and  execute  times  for  the  Eratosthenes  Sieve  prime 
number  generator.  See  references  1  and  2  (page  26)  for  details. 

34 
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Listing  1. 

(  38) 

63  SLDCN1 

Augusta  Source  Code  for  Prime  Number  Generation 

(  39) 

(  40) 

11  STO 

58  SLAO  6 

(  42) 

64  SLDCO 

2  0 

0  0  —  Eratosthenes  Sieve  Prime  Number  Program 

(  43) 

24  IND 

3  0 

0  0  —  in  ftugusta 

(  44) 

58  SLAO  6 

4  0 

0  0 

(  46) 

65  SLDC1 

5  0 

0  0  PROCEDURE  PRIME  IS 

(  47) 

24  IND 

6  1 

0  -14  PRIME,*, COUNT  :  INTE6ER; 

(  48) 

1  LDCI  16378 

7  1 

0  6  FLA6S  :  ARRAYI8190)  OF  BOOLEAN; 

(  511 

42  CSP  12 

8  1 

0  16388 

(  53) 

3  LLA  16390 

9  1 

0  16388  BEGIN 

(  561 

64  SLDCO 

to  1 

0  16388  PUTLINE < *  10  ITERATIONS*); 

(  57) 

11  STO 

11  1 

17  16388  FOR  ITER  IN  1..10 

(  58) 

2  LDL  16390 

12  1 

26  16388  LOOP 

(  61) 

1  LDCI  8190 

13  1 

30  16390  COUNT  :=  0; 

(  64) 

27  LEOI 

14  1 

34  16390  FLAGSI0)  :=  TRUE;  —  Initialize  Array 

(  65) 

38  FJP  71  =>  139 

IS  1 

40  16390  M0VELEFT  (  JFLAGS(O),  JFLAGS(l),  16378); 

(  68) 

58  SLAO  6 

16  1 

53  16390  FOR  I  IN  0..8190 

(  70) 

5  LDO  16390 

17  1 

64  16390  LOOP 

(  73) 

24  IND 

ie  i 

68  16392  IF  FLAGS(I)  THEN 

(  74) 

12  SINDG 

19  1 

78  16392  PRIME  :=  I  ♦  I  ♦  3; 

(  751 

38  FJP  55  =>  133 

20  1 

90  16392  K  i=  I  ♦  PRIME; 

(  78) 

58  SLAO  0 

21  1 

99  16392  NHILE  K  <=  8190 

(  801 

5  LDO  16390 

22  1 

104  16392  LOOP 

(  83) 

5  LDO  16390 

23  1 

108  16392  FLAGS (K)  :=  FALSE; 

(  86) 

19  ADI 

24  1 

115  16392  K  !=  K  +  PRIME; 

(  87) 

67  SLDC3 

25  1 

123  16392  END  LOOP; 

(  88) 

19  ADI 

26  1 

123  16392  COUNT  :=  COUNT  *  1; 

(  89) 

11  STO 

27  1 

133  16392  --  PUTSTR ( "PRIME  #=*); 

(  901 

58  SLAO  2 

28  1 

133  16392  --  PUTINT (PRIME); 

(  92) 

5  LDO  16390 

29  1 

133  16392  --  NENLINE; 

(  95) 

57  SLDO  0 

30  1 

133  16392  END  IF; 

(  97) 

19  ADI 

31  1 

133  16392  END  LOOP; 

(  98) 

11  STO 

32  1 

133  16392  END  LOOP; 

(  99) 

57  SLDO  2 

33  1 

139  16390  PUTINT (COUNT);  PUTLINEl"  PRIMES*); 

(  101) 

1  LDCI  8190 

34  1 

160  16388  END; 

(  104) 

27  LEOi 

(  105) 

38  FJP  18  =>  126 

(  108) 

58  SLAO  6 

(  110) 

57  SLDO  2 

(  112) 

24  IND 

(  113) 

64  SLDCO 

Listing  2. 

(  114) 

11  STO 

Disassembly  of  the  Object  Code  Into  P-Codes 

(  115) 

58  SLAO  2 

(  117) 

57  SLDO  2 

(  1191 

57  SLDO  0 

Dissasseibly  of  Augusta  Program:  SIEVE. CPL 

(  121) 

19  ADI 

Number  of  Procedures  =  1 

(  122) 

11  STO 

(  123) 

37  UJP  -27  =>  99 

Procedure  I  1 

(  126) 

58  SLAO  4 

Local  Siz 

=  16392 

(  128) 

57  SLDO  4 

Parameter 

Size  =  0 

(  130) 

65  SLDC1 

Lex  Level 

=  1 

(  131) 

19  ADI 

(  132) 

11  STO 

(  133) 

80  INCL  16390 

Offset 

Opcode  Value  Parameters 

(  136) 

37  UJP  -81  =>  58 

(  0) 

13  LCA  13  *10  ITERATIONS* 

(  139) 

80  INCL  16388 

(  15) 

42  CSP  2 

(  142) 

37  UJP  -123  =>  22 

(  171 

3  LLA  16388 

(  145) 

57  SLDO  4 

(  20) 

65  SLDC1 

(  147) 

42  CSP  4 

(  21) 

11  ST0 

(  149) 

13  LCA  7  *  PRIMES* 

(  22) 

2  LDL  16388 

(  1581 

42  CSP  2 

(  25) 

74  SLDC10 

(  160) 

43  RET 

I  26) 

27  LEQI 

(  27) 

38  FJP  115  =>  145 

(  30) 

58  SLA0  4 

(  32) 

64  SLDC0 

(  33) 

11  ST0 

(  34) 

58  SLA0  6 

(  36) 

64  SLDC0 

(  37) 

24  IND 

End  Listing 
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cn  I 


A  Small-C 
Operating  System 


Want  to  experiment  with  operating  systems?  Well, 
here  is  the  source  code  of  a  system  written  in  the 
programming  language  “C”  and  developed  using 
Ron  Cain’s  Small-C  compiler  ( DDJ  No.  45). 

As  I  was  lucky  enough  to  have  had  access  to  a  UNIX 
system,  I  was  able  to  bring  up  the  Small-C  compiler  with  a 
minimum  of  fuss.  After  a  couple  of  weeks  of  spare  time,  I 
was  able  to  return  to  the  microprocessor  system  and  run  the 
compiler.  It  was  then  that  the  contrast  between  the  large 
UNIX  system  and  a  micro  system  became  obvious.  In  par¬ 
ticular,  I  missed  the  ability  to  redirect  input/output  via  the 
operating  system.  With  UNIX,  any  program  output  destined 
for  the  console  can  be  redirected  to  go  to  a  file.  Console 
input  to  a  program  can  also  be  arranged  to  come  from  a 
file.  Both  functions  can  be  easily  specified  on  the  command 
line  (see  “echo”  later). 

Many  of  the  operating  systems  for  micros  were  developed 
in  the  days  when  32Kbytes  of  memory  was  a  large  amount 
for  a  microprocessor  system.  Now  it  is  by  no  means  unusual 
for  even  personal  machines  to  have  64Kbytes.  A  portion  of 
this  extra  capacity  could  be  devoted  to  making  the  micro 
operating  system  more  flexible.  Initially,  I  was  simply  trying 
to  add  routines  to  the  micro  to  implement  I/O  redirection. 

It  was  an  ideal  opportunity  to  try  out  the  Small-C  compil¬ 
er.  However,  after  a  very  short  time  I  found  that  I  seemed  to 
have  a  great  many  of  the  routines  of  a  full  operating  system. 
As  an  exercise,  I  then  decided  to  have  a  go  and  write  a  full 
system  and  this  article  is  the  result. 

I  have  incorporated  the  UNIX  process  of  having  directo¬ 
ries  as  files  themselves.  While  this  may  seem  unusual,  it  does 
lead  to  advantages  in  that  many  of  the  system  routines,  availa¬ 
ble  for  file  access,  can  be  used  to  process  directory  informa¬ 
tion.  User  programs  can  just  as  easily  access  directories  as  files. 

The  system  loads  and  executes  user  programs  at  100  hex 
to  make  possible  the  execution  of  CP/M-compatible  programs 
if  the  source  code  is  not  available.  These  programs  would 
require  some  form  of  interface  to  translate  system  calls  from 
CP/M  convention  to  the  form  expected  by  the  described  sys¬ 
tem.  As  an  alternative,  the  system  calls  described  could  be 
altered  to  give  a  CP/M-compatible  interface.  While  it  is  possi¬ 
ble  to  add  such  an  interface,  this  may  not  be  worth  the  effort. 
The  book,  Software  Tools]  gives  the  source  code  of  many 
useful  programs,  even  a  sophisticated  editor.  These  are  written 
in  Ratfor  but  it  is  not  a  difficult  task  to  translate  to  “C”  and 
this  would  allow  the  use  of  more  sophisticated  system  calls 
and  make  possible  the  transfer  of  programs  to  other  systems. 

In  all  of  my  work  so  far,  I  have  used  the  Small-C  compiler 
as  published  {DDJ  Nos.  45,  48)  with  modifications  enabling 
backlash  escape  sequences  in  literal  characters  {DDJ  No.  56) 
and  the  removal  of  the  bugs  in  the  arithmetic  rotate  routines 
{DDJ  No.  52).  One  of  the  more  advanced  versions  now  being 
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sold  would  make  the  translation  and  compilation  of  any  pub¬ 
lished  “C”  programs  easier.  Remember  that  source  code  will  be 
required  if  you  want  to  bring  up  the  compiler  on  a  new  system 

Characteristics  of  this  operating  system  are:  input/output 
redirection  on  the  command  line;  hierarchical  directories 
(directories  of  directories  and  files);  directories  able  to  be  pro¬ 
cessed  as  files;  a  copy  in  memory  of  the  pointers  used  in  file 
maintenance  (giving  fast  file  access);  a  disk  group  of  5  12  bytes 
(could  be  altered);  or  pointer  range  of  32767  disk  groups; 
parsed  command  line  arguments  passed  to  user  programs  (see 
UNIX  argc,  argv[  ]);  and  dynamic  memory  allocation  of  512- 
byte  blocks. 

A  disadvantage  of  the  system  as  it  stands  is  that  it  has 
been  developed  for  a  one-disk-drive  machine.  Simultaneous 
access  of  multiple  drives  would  require  either  swapping  of  the 
directory  pointer  blocks  to/from  the  drives  or  maintenance  of 
all  pointer  arrays  in  memory.  While  using  more  memory,  the 
second  alternative  is  the  more  time  efficient.  Allocating  the 
top  16K  of  memory  to  the  system  program  and  the  pointer 
arrays  would  allow  the  addressing  of  greater  than  1Mbyte  of 
disk  space.  The  upper  limit  of  disk  space  is  the  pointer  range 
of  32767  disk  groups  or  16  megabytes  with  512  byte  group 
size.  Large  system  size  would  make  memory  storage  of  arrays 
wasteful  and  an  alternative  file  structure  is  described  towards 
the  end  of  this  article  that  would  be  a  good  basis  for  larger 
capacity  systems. 

File  Structure 

There  are  three  pointer  arrays  being  swapped  between 
disk  and  memory:  glinks[],  loptr[] ,  and  hiptr [ ]  (see  Listing 
on  page  41).  The  largest  array  is  glinks[].  For  any  group  “i” 
on  disk,  the  next  group  in  the  linked  list  from  group  “i” 
would  be  glinks[i] .  If  glinks[i]  is  zero,  it  indicates  the  end  of 
a  list  of  groups,  i.e.,  end  of  a  file  (Figure  1 ,  page  37).  There  is  a 
linked  list  for  each  file,  a  list  of  free  groups  left  on  disk,  and 
even  a  short  linked  list  that  the  system  uses  to  load  and  save  an 
image  of  the  arrays  glinks-loptr- hiptr  on  disk. 

Files  are  tied  into  a  directory  structure  by  the  arrays 
loptrf  ]  and  hiptr [  ] .  A  directory  is  simply  a  linked  list  of  files 
and  this  is  achieved  using  the  array  loptr[]  with  loptr[k]  used 
to  index  the  next  file  in  loptr[] .  See  Figure  2,  page  37,  for  a 
pictorial  representation  of  this  and  the  following  arrange¬ 
ments.  If  loptr[k]  is  zero,  then  the  last  file  in  the  current 
directory  has  been  reached.  If  the  value  of  hiptr [  ]  for  a 
given  directory  element  is  positive,  it  is  taken  to  be  a  pointer 
to  the  first  group  of  a  file,  with  the  array  glinks[  ]  linking 
further  groups  of  the  file.  If  negative,  this  element  of  the  direc¬ 
tory  is  taken  to  be  a  further  directory  and  the  negative  value  is 
complemented  and  used  to  index  back  into  the  directory 
array  loptr[  ] . 

The  first  entry  in  a  directory  is  always  a  file  of  the  names 
of  files  in  that  directory,  one  name  per  line.  As  an  end-of-line 
character  is  used  as  a  name  delimiter,  there  is  virtually  no  limit 
to  name  length.  The  nth  line  refers  to  the  nth  entry  along  the 
loptr[  ]  list  for  that  directory.  If  there  are  32  lines  in  the  file 
of  filenames  for  a  directory,  then  it  must  be  possible  to  index 
through  the  loptr[  ]  array  32  times  and  find  a  zero  in  that 
element  of  loptr[  ] ,  i.e.  the  expected  end  of  that  directory  list 
of  files. 

The  first  file  name  in  a  directory  file  is  always  a  file  called 

and  is  a  reference  to  the  file  of  filenames  for  that  directory. 
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On  power-up,  the  system  will  always  get  loptr[2]  (one  of 
a  few  reserved  locations)  and  assume  that  this  pointer  points 
to  the  user’s  directory.  When  the  system  opens  a  file,  given  the 
name,  it  scans  the  directory  (see  “scndir(name),”  system  call) 
and  when  the  line  number  of  the  entry  is  known,  it  indexes 
into  the  loptr[  ]  array  this  number  of  times.  If  the  hiptr  of 
this  entry  is  negative,  the  entry  must  be  another  directory;  if 
positive,  it  is  the  first  disk  group  of  a  file  entry. 

As  already  mentioned,  redirection  of  console  input  and 
output  has  been  incorporated  in  this  sytem.  When  the  char¬ 
acter  “>”  is  encountered  on  the  command  line,  the  next 
characters  are  assumed  to  be  a  filename,  a  file  of  that  name  is 
created,  and  any  program  output  that  would  have  been  put  to 
the  console  will  go  to  that  file.  Similarly,  the  character  “<” 
indicates  that  any  requests  by  the  executed  program  for  con¬ 
sole  input  will  be  taken  from  the  file  whose  name  follows  the 
“<”  character. 

System  Overview 

The  flexibility  of  the  overall  system  becomes  obvious 
when  the  simple  program  “echo”  is  considered: 

main() 

{  while(putchar(getchar()));} 

Execution  of  this  program  echoes  typed  characters.  They  will 
be  doubly  echoed,  as  I  have  written  getchar  to  echo  any  non¬ 
control  characters.  If,  on  the  command  line,  we  say  “echo 
>newfile,”  any  characters  typed  at  the  console  will  be  re¬ 
directed  into  the  file  “newfile.”  If  a  file  by  that  name  already 
exists,  then  it  will  be  replaced.  To  terminate  the  process, 
type  control  d.  This  gives  the  end  of  file  code.  Then,  on  the 
command  line  “echo <  newfile”;  the  file  will  then  be  listed  to 
the  console,  as  the  input  to  echo  has  been  redirected  from 
console  to  come  from  “newfile.”  “echo  <newfile  >newerfile” 
gives  a  copy  of  newfile  into  newerfile.  Now  “echo  <.”,  the 
contents  of  the  file  which  is  the  file  of  filenames  for  the 
current  working  directory,  will  be  shown. 

When  the  user  changes  his  working  directory  using  the 
system  call  “chdir,”  the  value  of  loptr[  ]  for  the  new  directory 
is  stored  in  loptr [  3  ] .  The  default  directory  for  the  user  is  in 
loptr[2] .  If  “chdir”  is  called  with  a  zero  argument,  the  user  is 
returned  to  his  default  directory  from  wherever  he  is.  If  a 
program  to  be  executed  cannot  be  found  in  the  working  direc¬ 
tory,  the  system  directory  will  be  searched  by  default.  The 
system  directory  is  pointed  to  by  loptr[  1  ] . 

A  list  of  the  system  calls  is  in  Table  1.  The  listing  of 
“library  for  Small-C  system  programs”  gives  details  of  how 
getchar  and  putchar  are  formed.  A  function  that  illustrates 
some  system  calls  and  is  also  required  by  the  Small-C  compiler 
on  the  new  system  is  that  of  “fopen”  (note  that  I  have  altered 
the  second  argument  to  be  an  “int”). 

fopen(name,func) 
char  name]  ]  ; 
int  func; 

\ 

int  buffa; 

if((buffa=alloc())==0 (return  0;/*  get  a  buffer  */ 
if(func==rdfn)return  (openf(name,buffa,rdfn)); 
if(func==wrfn)return  (creatf(name, buffa)); 
dalloc(buffa);  /*  error- give  buffer  back  */ 
return  0 ; 


System  Transfer 

It  is  not  enough  to  have  a  copy  of  the  system  code  on  the 
disk,  as  the  initial  directory  also  needs  to  be  there  and,  as  there 
are  no  intrinsic  functions  in  the  system,  there  should  be  at 
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least  a  memory  to  disk  save  program  on  the  disk  as  well.  My 
memory  save  program  takes  a  numeric  argument  and  saves  that 
number  of  groups  beginning  at  a  predetermined  location.  One 
way  to  get  going  would  be  to  put  sectors  onto  the  disk  manu¬ 
ally  but  there  is  another  easier  way.  1  started  debugging  the 
system  by  assembling  it  down  low  in  memory  and  having  the 
disk  I/O  routines  simply  doing  block  moves  to  and  from  higher 
memory.  Simple  programs  and  text  could  be  loaded  into  mem¬ 
ory  at  the  appropriate  location  and  loaded  by  the  Small-C 
system  as  if  coming  from  disk. 

At  this  stage,  the  directory  loader  routine  generated  a 
dummy  directory  with  three  files,  each  of  four  groups  (2K),  a 
free  group  list  and  a  free  pair  (loptr-hiptr)  list.  The  free  group 
list  is  simply  a  long  file  pointed  to  by  hiptr[2].  The  free  pair 
list  is  a  linked  list  of  any  spare  loptr[  ]  cells  and  is  used  when 
a  new  file  or  directory  is  created.  This  linked  list  of  cells  is 
pointed  to  by  hiptr[  1  ] .  When  the  bugs  were  out  of  the  system, 
I  altered  the  disk  write  routine  to  actually  write  information 
to  the  disk.  I  then  had  a  suitably  formatted  disk  for  the  new 
system.  After  copying  this  disk  (twice),  I  recompiled  the  sys¬ 
tem  to  reside  in  high  memory,  altered  the  disk  read  to  come 
from  disk  instead  of  memory,  and  the  system  was  up. 

The  system  code  takes  up  about  9.5 K  and  the  pointer 
buffers  about  2.5K  for  my  250K  drive.  One  system  call  I  will 
be  changing  in  the  future  is  “scndir.”  Filenames  will  be  al¬ 
lowed  to  contain  “?”  (match  with  any  character)  and 
(match  with  any  number  of  characters).  A  second  parameter 
will  also  be  passed  and  this  will  tell  scndir  what  line/entry  in 
the  directory  to  begin  the  search  with.  Another  area  that  I  will 
be  modifying  will  be  the  system  of  group  linking  for  disk  files. 
The  group  links  will  be  part  of  the  files  on  disk  eliminating  the 
large  array  “glinks”  (Figure  3). 


First  group  used  as 
pointers  to  groups. 


Data  groups  of  the 
file. 


Last  pointer  links 
to  another  group 
of  pointers. 


Figure  3. 

A  proposed  file  structure  that  would  remove  the  need  for 
an  in -memory  array  of  group  links  (glinks). 


System  calls 

Descriptions 

puterr(str) 

Put  a  string  to  the  console  (cannot 
be  redirected,  used  for  error 
messages). 

getc(unit) 

Get  a  character  from  “unit,” 
unit=0  standard  input,  unit=  1  the 
communication  port,  returns 
character  or  0  on  end  of  file. 

putc(c,unit) 

Put  a  character  to  “unit”  (see  getc), 
returns  “c”. 

readf(unit) 

Read  the  next  sequential  group  on 
opened  file,  returns  0  on  end  of 
file. 

writef(unit) 

Write  the  next  sequential  group. 

openf(name,buffer,fn) 

Open  “name”  for  read(fn=l) 
write(fn=2)  or  append  (fn=3)  with 
“buffer”  as  the  buffer  address, 
returns  a  unit  number  or  0  if  not 
found. 

create(name, buffer) 

As  for  openf,  write  assumed,  any 
old  file  by  that  name  is  lost. 

closf(unit) 

Close  the  given  unit  number, 
flushes  write  buffer  if  required. 

readr(unit,N) 

Read  nth  group  from  opened  unit 
number,  returns  0  if  out  of  file 
group  range. 

writer(unit,N) 

Write  nth  group  to  opened  unit 
number,  returns  0  if  out  of  range. 

scndir(name) 

Scan  the  working  directory  for 
“name,”  returns  number  of  entry  in 
directory,  1  to  n  or  0  if  not  there. 

chdir(name) 

Look  for  “name”  in  the  current 
directory  and  if  it  is  a  directory, 
change  operations  to  it,  if  name==0 
changes  back  to  root  directory  of 
user. 

mkdir(name) 

Create  a  new  directory  “name,” 
returns  a  0  if  name  in  use. 

rmfil(name,i) 

Remove  directory  entry  “name,”  if 
not  found,  returns  0.  Won’t  allow 
rmfil(“.”.  If  “i”  is  0,  won’t  allow 
directory  entry  removal.  If  “i”  is 

1,  a  recursive  remove  of  the  entry 
is  undertaken,  directory  or  file. 

alloc() 

Return  the  address  of  the  next  free 
top  5  12  byte  block  of  memory. 

Addr  will  lie  on  a  5 1 2  byte 
boundary. 

dalloc(addr) 

Give  back  a  5 1 2  byte  block  of 
memory  for  future  use. 

dirfn(i) 

For  directory  information:  i=0  re¬ 
turns  ptr  to  glinlcsfj,  i=l  returns  ptr 
to  loptr[  ],  i=2,  returns  ptr  to  hiptr. 

dirio(rw) 

Refresh  or  save  the  directory 
pointer  arrays:  rw=  1  (write)  gives  a 
save  to  disk,  rw=2  (read)  gives  a 
refresh  from  disk. 

Table  1 . 

System  Calls. 
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Conclusion 

While  I  have  a  compiler  on  the  system  (courtesy  of  Ron 
Cain),  I  do  not  yet  have  an  assembler  for  it.  If  any  reader  has 
written  an  assembler  (in  Small-C?)  for  8080  mnemonics,  I 
would  like  to  hear  from  them.  Good  luck! 

Listing  begins  on  next  page. 


Editor’s  Note:  For  those  who  have  not  yet  implemented  the 
Small-C  compiler  published  in  DDJ,  some  back  issues  are  still 
available.  The  greatly  improved  Small-C  v.2,  by  J.E.  Hendrix, 
is  available  in  issues  #74  and  #75.  Ron  Cain’s  version  one  of 
the  compiler,  along  with  bug  fixes  and  patches,  can  most  easily 
be  found  in  our  Bound  Volumes. 


Reference 

1  Kernighan,  B.W.  and  Plauger.  Software  Tools.  Addison- 
Wesley,  Reading,  Massachusetts,  1976. 
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Small-C  Operating  System  (Text  begins  on  page  36) 
Listing  One 


/**  operating  system  written  in  Small-C  **/ 

/**  Brian  HcKeon  5/5/82  **/ 

/'define  eol  10  /*  end  of  line  char  */ 

/'define  bufsiz  512  /*  disk  buffer  size  */ 

/#*  some  memory  control  **/ 

/'define  usrprg  256  /*  start  and  entry  point  of  user  program  */ 
int,  nemrnap[8];  /*  bitmap  of  512  byte  blocks  of  memory  */ 

/**  and  directory  structure  **/ 

//define  dirone  22  /*  ptr  to  1st  grp  of  gl inks-loptr-hiptr  */ 

//define  lnksiz  500  /*  one  link  per  ’bufsiz'  bytes  */ 
int  glinks [lnksiz] ; 

//define  ptrsiz  50  /*  seems  to  be  enough  */ 

int  loptr [ptrsiz] ; 
int  hiptr[ptrsiz] ; 

/**  First  few  pointer  pairs  have  special  functions  “*/ 

/**  zero  ptrs  are  set  to  to  0  as  traps  **/ 

//define  rsvptrs  't  /*  reserved  system  pointer  pairs  */ 

/-'define  sysdir  loptr[1]  /*  ptr  to  system  dir  struct  *'/ 

/'define  userdir  loptr[2]  /*  ptr  to  root  dir  of  user  */ 

/'define  workdir  loptr[3]  /*  ptr  to  -current-  user  dir  structure  */ 

/'define  freptr  hiptr[1]  /*  ptr  to  free  dotted  pair  list  */ 

//define  grpfree  hiptr[2]  /*  ptr  to  first  free  disk  group  */ 

/**  i/o  structures  **/ 

int  stdout;  /*  and  for  standard  output  */ 

/'define  maxunits  10  /*  max  no.  simul  open  files  */ 

//define  minunit  2  /*  0,  1  reserved  for  console  and  communication  port  */ 

int  grwfmaxunits ] ;  /*  0  if  free,  ’rdfn’  for  read  and  ’wrfn’,  v;rite  */ 
//define  rdfn  1 
//define  wrfn  2 

//define  anfn  3  /*  append,  used  for  openf  call  only  */ 

/**  structures  to  keep  track  of  file  i/o  **/ 

int  firgrp[maxunits] ;  /*■  first  group  of  a  file  group  list  */ 

int  InlcgrpTmaxunits] ;  /*  link  group  for  sequential  i/o  */ 

int  gbuffs[maxunits] ;  /*  addr  of  the  buffers  assoc  with  a  unit  */ 

int  gptrs [maxunits ] ;  /*  pointers  into  these  buffers  * / 

char  sysinpfbufsiz] ;  /*  system  input  buffer  */ 

char  sysout[bufsiz] ;  /*  and  output  buffer  */ 

/**  command  line  argument  passing  to  user  programs  **/ 
int  argc;  /*  argument  count  */ 

int  argv[10];  /*  array  of  ptrs  to  argument  strings  */ 

/**  line  input  buffer  -  argv[]  strings  **/ 

//define  maxlin  128  /*  max  line  input  size  */ 

char  linbuf [maxlin] ;  /*  line  input  buffer  */ 

/**  main  entry  point  for  system  **/ 

/*  call  the  system  with  the  desired  i/o  parameters  */ 

/*  with  argO  the  number  of  the  system  call  V 
/*  */ 

/'asm 

org  0an00h 
//endasm 

/*  OaOOO  gives  blocks  1  to  70  spare  */ 

/'define  maxblk  77  /*  leave  a  couple  of  blocks  for  stack  */ 

system(arg0,arg1 ,arg2,arg3) 
int  argO , argl , arg2 , arg3 I 
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{ 

int  munit.savedir ; 

if (arg0==0)return  ( puts (argl  ) ) ;  /*  put  str  to  std  err  */ 

if  (arg0==1  )return  (getoCargl ) ) ;  /*  char  fetch  *f 

if (argO==?)return  (putcCargl ,arg2) ) ;  /*  char  put  */ 

if (arg0==3)return  (readf (argl ) ) ;  /*  sequential  read  */ 

if  (arg0==i4  )return  (uritef  (argl  ) ) ;  /*  sequential  write  */ 

if (arg0==5)return  (openf (argl , arg2,arg3 ) ) ;  /*  open  a  file  */ 

if (arg0==6 )return  (creatf  (argl  ,arg2) ) ;  /*  create  a  file  */ 

if (arg0==7)return  (closf (argl ) ) ;  /*  close  a  unit  */ 

if (argO==R )return  (readr(arg1 ,arg2) ) ;  /*  read  random  grp  */ 

if (arg0==9)return  (writer (argl , arg2 )) ;  /*  write  random  */ 

if (arg0==10 )return  (scndir (argl  ) ) ;  /*  scan  dir  for  file  name  */ 

if (argn==l 1 )return  (chdir (argl ) ) ;  /*  change  directory  */ 

if (arg0==12)return  (mkdir (argl ) ) ;  /*  make  new  dir  */ 

i f ( arg0  =  =  1 3 ) return  ( rnf i 1 (argl , arg2 ) ) ;  /*  remove  file-directory  */ 

i  f  ( argO  =  =  1  il )  return  (alloc());  /*  get  addr  of  free  blk  */ 

if (arg0  =  =  15)return  (dalloc(arg1  ) ) ;  /*  de-alloc  a  men  hlk  */ 

i f(argO=r 1 6)return  (dirfn (argl ) ) ;  /*  give  addr  of  dir  in  mem  */ 

if (arg0==17)dirio(wrfn) ;  /*  go  system,  save  the  dir  */ 

else  { inits ( ) ; dir io( rdfn ) ; 

putsC'illegal  system  call  >17;  directory  restored\n" ) ; 

} 

while(l)  /*  command  interpreter  loop  */ 

{ 

inits();  /*  re-initialize  stk ,  i/o,  hardware  */ 

putsC'.f.  ");  /*  prompt  to  user  */ 

if ( (nunit  =  getl in ( 1 inbuf ) )  =  =0 )continue  ;  /*  get  command  */ 
if (parslin ( 1  inhuf ,mun.it )  ==D )  /*  parse  into  argc,  argv  V 

continue;  /*  on  parse  error  */ 

if ( (munit=openf (argv[01,sysinp,rdfn) )==n) 

{ 

i f (workdir  =  =  sysdir ) f puts ( "open  errorXn" ) ; continue ; } 
else 


savedir=workdir ;  /*  save  the  working  dir  */ 
workdir  =  sysdir ;  /*  and  look  in  the  sys  dir  */ 
muni t  =  openf (argv TO  1 , sysinp , rdfn ) ; 
workdir=savedir; 

if (muni t==0 ) {puts ( "open  error\n" ); continue ; } 

} 


} 


i f ( loadf (muni t ) r =0 )continue ;  /*  and  load  the  file  */ 
closf (munit) ;  /*  close  the  loader  unit  */ 


usrprg ( argc , argv) ; 
closf ( stdout ) ; 
dirio(wrfn ) ; 


/*  call  the  loaded  user  program  */ 
/*  flush  the  output  if  any  */ 

/*  and  save  the  dir  */ 


} 


} 


/*  get  the  next  line  of  input  from  the  console  */ 

/*  all  white  space  is  replaced  by  nulls  (n)  for  parsing  */ 

//define  backsp  8 
getlin (buff a ) 

char  buf  fa  [  1 ;  (Continued  on  next  page) 
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Small-C  Operating  System  (Listing  continued,  text  begins  on  page  36) 


{ 

int  k; 
char  c; 
k  =  0; 

while (Krax]  in) 

{ 

c=inchar ( ) ; 

if ( c==eol )break ; 

if (c==backsp) 

{ 

if (k) { — k ;outchar (c) ; ] 
continue ; 

} 

if (c<= '  ' )c=0; 
buff a  T k  +  + l  =  c ; 

) 

buf fa  Tk ] =0 ; 
return  k; 

} 

/*  parse  a  line  into  argc,  argv  and  also  re-direct  i/o  */ 
par si  in (str , nchar ) 
char  strT]; 
int  nchar; 

{ 

int  pt.endarg; 
char  lastc; 
pt=argc=0 ; 
arp,v[n  ]  =  &st.r  [0  ] ; 
wh i 1 e  ( 1  ) 


while(str[pt] )++pt;  /*  move  over  argument  */ 
while(str[pt]==0)++pt;  /*  and  nulls  */ 
i f (pt>nchar ) break  ;  /*  finished?  */ 

if (str f pt ]==’>' )  /*  check  for  re-direction  */ 

{ 

if ( (stdout=creatf (£str[pt+1 l.sysout) )  =  =(">) 

fputs("i/o  redirection  error\n" ); return  0;} 


else  if (str Tpt ]=='<' ) 

{ 

if ( (stdin=openf (&str[pt+1 ],sysinp,rdfn))==n) 

{puts("i/o  redirection  error\n" ); return  0;} 

} 

else  argvT++argc]=&str [pt ] ; 

} 

return  ++arp,c; 

} 

/*  open  a  given  file  name  for  file  i/o  * / 

/*  from  the  current  directory  */ 

/*  rw  is  'rdfn*  for  input,  'wrfn'  for  output  and  'apfn'  for  append  r/ 
open f (name , buffer , rw) 
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char  name! ] .buffer!  ] ; 
int  rw; 

{ 

int  filno; 

if ( (filno=scndir (name) )==0)return  0;  /*  find  file  name  */ 

return  (open it ( f il no, buffer , rw) ) ; 

} 

/*  lower  level  open  operates  from  number  entry  of  file  in  dir  */ 

/*  for  example  1  would  open  the  dir  file  itself  */ 

/*  the  append  function  should  only  be  used  with  null  terminated  */ 
/*  files  as  it  searches  for  this  null  char.  */ 

openit(filno.buffer.rw) 
int  filno; 
char  buffer!]; 
int  rw; 


int  i.k.grp; 
i =workdir ; 

while( — f ilno) i=loptr f i ] ;  /*  down  the  dir  list  */ 
if (hiptr [ i ] <0 )return  0;  /*  attempting  to  open  dir?  */ 

if ( (filno=findio( ) )==0)return  0;  /*  any  i/o  units  left?  */ 
f irgrp! f ilno]=hiptr [ i ] ;  /*  pointer  to  first  grp  of  file  */ 

gbuffs[filno]=buffer ;  /*  setup  buffer  location  */ 
if(rw==rdfn)  /*  read  ?  */ 

{ 

grw[ filno ]=rdfn ; 

lnkgrpffilno] =hiptr [ i ] ; /*  read  from  this  first  group  */ 
gptrs[filno]=bufsiz;  /*  initialize  the  pointer  */ 

} 


i f ( rw=rwrf n ) 

i 

/« 

write  ?  */ 

i 

frefil (hiptr[ i] ) ; 

/« 

free  up  the  old  groups  */ 

hiptr [ i ] =0; 

/* 

initially  append  null  */ 

grw[filno]=wrfn ; 

/* 

write  */ 

lnkgrpf  fil no]=-i ; 
gptrs[filno]=0; 

} 

i f ( rw: =apfn ) 

/* 

by  indicate  a  link  to  the  dir! 

/*  initialize  the  pointer  */ 

/* 

append  ?  */ 

{ 


/*  get  to  the  last  group  */ 
grp=hiptr[i] ; 

i f (gl inks [ grp] r =0 )lnkgrp[filno]=-i; 
else 

{ 

wh ile ( gl inks [gl inks [grp] ] ! =0 )grp=gl inks [ grp] ; 
lnkgrp[filno]=grp;  /*  2nd  last  grp  */ 
grp=glinks[grp] ;  /*  last  grp  */ 

} 

if (grupio (grp, buffer ,rdfn)==0)return  0;  /*  read  last  grp  */ 
frefil(grp);  /*  and  give  it  up  */ 

grw[filno]=wrfn ; 
k  =  0 ; 

(Continued  on  next  page) 
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Small-C  Operating  System  (Listing  continued,  text  begins  on  page  36) 


while(buffer Tk] ! =0 )++k ;  /*  go  to  the  old  eof  */ 

gptrs[filno]=k ;  /*  pointer  now  ready  for  append  */ 

1 

return  filno; 

} 

/*  create  a  file  */ 
creatf (name.buffa) 

char  nane[] , buffa[ ] ; 

{ 

int  unit ,k , 1 .newfree ; 

if( (grpf ree==0 ) ! (freptr  =  =  0) ! (name[0 ]  =  =0 ) ) return  0; 

if (unit=openf (name, buffa, wrfn) )return  unit;  /*  in  the  dir?  */ 

if ( (unit=openit ( 1 , buffa ,apfn ) )==0 )return  0;  /*  no,  open  the  dir  */ 

k=workdir;  /*  and  append  the  file  */ 

while(loptr  [k]  )k=lopt.r  [k] ;  /*  go  down  the  dir  list  */ 

newf ree=loptr [freptr ] ;  /*  get  a  new  free  pointer  */ 

loptrn<]=freptr ;  /*  and  add  to  the  directory  */ 

loptr[freptr]=0;  /*  append  a  null  */ 

hiptr[freptr]=0;  /*  and  no  groups  */ 

freptr=newf ree ;  /*  up-date  free  pointer  */ 

IrO;  /*  errors  after  this  point  are  fatal  */ 

whileCnameTl] )  /*  append  the  name  */ 

if (putc(name[l++],unit)==0)  /*  to  the  dir  file  */ 
createrr (k) ; 
if (putc(eol ,unit)==0) 
createrr (k) ; 

closf(unit);  /*  and  close  the  directory  */ 

return  (openf (name, buffa, wrfn) ) ;  /*  openf  should  now  work  */ 

} 

/*  fatal  error  routine  from  create  function  */ 

/*  dont  flush  the  dir  buffer  as  there  is  an  error  somewhere  */ 
createrr (k) 
int  k; 

{ 

int  oldfree; 
oldfree=freptr; 
frept,r  =  loptr  [k] ; 

loptrTk]=0;  /*  re-terninate  the  dir  */ 
loptr [f reptr ]=oldfree; 

putsC'fatal  failure  on  file  create\n"); 
system( 1 7, 0, 0, 0) ;  /*  and  try  to  recover  */ 

} 

/*  close  a  given  unit  number  */ 
closf (unit) 
int  unit; 

! 

int  k ; 

k=1 ;  /*  default  return  value  */ 

if (unit<minunit)return  n;  /*  trap  illegal  close  */ 

if ( (grw[unit]  =  =wrfn)^(gptrs[unit] » =0 ) )  /r  write  required?  V 
k=v;ritef  (unit) ; 

grw[unit]=0;  /*  now  free  up  this  unit  */ 
return  k; 

} 
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/*  look  for  a  spare  unit  number  else  return  0  */ 
f  inci io ( ) 

{ 

int  k; 

kminunit; 

while (k<mn xuni ts ) 

{if(grwrk]==0)return  k;++k;} 
return  0; 

} 

/*  scan  directory  for  a  matching  line  to  the  given  one  */ 

/*  and  return  a  number  1  to  N,  else  zero  if  not  found  */ 
scndir (name) 

char  nane[]; 

{ 

int  linnum,munit,k , fig; 
char  c; 

if (name[n]==n)return  0; 

if ( (munit=openi t ( 1 , sysinp ,rdfn ) ) ==0 )return  0;  /*  open  dir  for  read  */ 

linnum=0; 

while ( 1  ) 

{ 

fip.=i : 
k  =  0; 

++1 innum; 
wh i 1 e ( 1  ) 

{ 

if ( (c=getc(nunit) )==0) {closf (munit) ; return  0; ) 

if (c==eol ) break ; 

if  (c  !  =namerk++]  )flg=0; 

} 

if ( (name[k]==0)£flg) {closf (munit) ;return  linnum; } 

} 

) 

/*  put  an  error  message  to  the  console  */ 
puts (str ) 

char  str[]; 

{ 

int  j ; 
j=0; 

while ( (outchar (str [ j++] ) ) ! =0 ) ; 

} 

/*  get  a  character  from  a  given  unit  number  */ 
getc(unit) 

int  unit; 

{ 

char  c; 

if (unit  ==0)unit  =  striin ;  /*  standard  in?  -  re-direct  */ 

if (unit ==0) return  (inchar());  /*  console  port  */ 
if (unit==1 )return  (incom());  /*  communication  port  */ 
if  ( grivtunit ] !  =rdfn )return  0;  /*  open  for  read? 

if (gptrs[unitl==hufsiz)  /*  get  pointer  -  empty?  */ 

if (readf (unit.)  =  =0)return  0; 
c  =  * ( gbuf  fs  f  unit 1+gptrsfunit ] ) ; 

++gptrs[unit] ; 
return  c; 

}  (Continued  on  next  page) 
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Small-C  Operating  System  (Listing  continued,  text  begins  on  page  36) 


/*  sequential  read  of  file  */ 
readf (unit) 
int  unit; 

{ 

int  nxtgrp; 

if (grw[unit] !=rdfn)return  0; 
gptrs[unit]=0; 
nxtgrprlnkgrpTunit] ; 

lnkgrpfunit]=g] inksCnxtgrp] ;  /*  update  grp  no.  */ 

return  (grupioCnxtgrp.gbuffsTunit] ,rdfn) ) ;  /*  refill  buffer  */ 

} 

/*  random  read  of  file  group,  range  0  to  N  */ 
readr (unit , grpno) 
int  unit, grpno; 

{ 

int  rdgrp; 

if (grw[unit] !=rdfn)return  0; 
rdgrp=fir grp [unit] ; 

while(grpno — )rdgrp=glinks[rdgrp] ;  /*  down  the  file  grp  list  */ 
return  ( prupio ( rdgrp, gbuffs  Tun  it ] , rdfn ) ) ; 

) 

/*  put  a  character  to  a  given  i/o  unit  */ 
putc(c.unit) 
char  c; 
int  unit; 

{ 

if (unit==0)unit=stdout;  /*  standard  out?  -  redirect  */ 

if  (unit-==0)return  (outchar(c) ) ;  /*  console  port  */ 
if (unit==1 )return  (outcom(c));  /*  communication  port  */ 
if (gruTunit] !=wrfn)return  0;  /*  write  unit?  #/ 

if (pptrsrunit]==bufsiz)  /*  full  buffer?  */ 

if (writef (unit)==0)return  0; 

*( gbuf f s [uni t]+gptrs [unit] )=c; 

++gptrs[unit] ; 
return  c; 

} 

write  sequential  to  given  unit  */ 
writef (unit) 
int  unit; 

{ 

int  nevjgrp; 

if (grw[unit] ! =wrfn ) return  0; 
gptrs [unit  1=0; 

newgrp  =  fregrp ( ) ;  /*  get  a  new  group  */ 

if  ( InkgrpTuni t. ] >0  )gl inksT Inkgrpf  uni t  ]  J  =newgrp ;  /*  link  */ 

else  hiptr T-lnkgrp[unit ]  ]  =newgrp ;  /*  special  case:  link  to  dir  */ 

lnkgrplunit] =newgrp ;  /*  and  ready  for  next  call  */ 

return  (grupio(newgrp,gbuff s[unitl , wrfn) ) ; 

} 

/*  random  write  of  file  group,  range  0  to  N  */ 
writer (unit, grpno) 
int  unit, grpno; 

{ 

int  wrgrp; 

i f ( grwfuni t ]  !=wrfn ) return  0 ; 
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wrgrp=firgrp[unit]; 

while(grpno — )wrgrp=glinksfwrgrp] ;  /*  down  the  file  grp  list  */ 
return  (grupio(wrgrp,gbuffs[unit] ,  wrfn) ) ; 

} 

/«  free  up  a  list  of  groups  */ 
frefil (grp) 
int  grp; 

{ 

int  fgrp;  /*  a  pointer  to  the  first  free  group  */ 
if (grp==0)return  0;  /*  dont  lose  the  free  list  */ 
fgrp=grpfree;  /*  a  pointer  to  the  first  free  group  */ 
grpfree=grp;  /*  point  free  list  at  the  file  */ 

while(gl inks [grp] )grp=glinksT grp] ;  /*  go  to  end  of  file  */ 
gl inks [ grp] =f grp;  /*  and  link  on  the  old  free  list  */ 

} 

/*  get  a  free  group  */ 

/*  null  terminate  */ 
f  regrpC ) 

{ 

int  grp; 

grpzgrpfree;  /*  find  the  next  free  group  */ 

grpfree  =  gl inks [ grp] ;  . /*  update  the  free  pointer  */ 

glinks[grp]=0;  /*  and  null  terminate  the  returned  group  link  */ 

return  grp; 

} 

/*  load  a  program,  checking  for  oversize  and  for  jump  at  sta^t  */ 
loadf (unit) 
int  unit; 

{ 

int  grp.addr ,blk; 
char  ujump; 

g,rp=lnkgrp[unit] ;  /*  get  the  first  group  */ 

addrmsrprg:  /*  load  into  the  user  area  */ 

blk=addr>>9;  /*  and  allocate  mem  as  you  go  * / 

while (grp) 

{ 

if (blk==maxblk) {puts ("program  too  large\n”) ; return  0;] 
if(grupio(grp,addr,rdfn)==0) {puts ( "load  error\n" ); return  0 ; } 
ad dr  =  addr+buf  siz ; 

f ixblk(++blk) ;  /*  allocate  the  mem  */ 
grp= gl inks [ grp ] ; 

} 

u jump=*usrprg;  /*  should  be  the  jump  byte  if  a  program  */ 
i f (ujump !  =-61 ) {puts ( "not  a  prograrrAn" ); return  0;} 
return  1 ; 

} 

( Continued  on  next  page) 
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Small-C  Operating  System  (Listing  continued,  text  begins  on  page  36) 


/*  save/restore  the  directory  structure  to/fron  disk  */ 
dirio ( rdwr ) 
int  rdwr; 

{ 

int  grp.addr; 
grp=dirone ; 
addr=glinks ; 
while(grp) 

{ 

if (grupio( grp.addr, rdwr )  =  r0)  return  0; 
grp=glinks[grp] ; 
addr=addr+bufsiz ; 

} 

} 

/*  change  work  directory  */ 
chdir (nane) 

char  nane[ 1 ; 

{ 

int  pt,n; 

if  (name==0)  {workdir=userdir ;return ; } 
if ( (n=scndir (nane) )==0) return  0; 
pt=workdir ; 

whi.le( — n)pt=loptr  [pt.l ;  /*  down  the  dir  list  */ 

if(hir  rrpt]>=0)return  0;  /*  not  a  directory  */ 
workdir=-hiptr[pt] ;  /*  it  is  a  dir,  change  */ 

} 

/*  make  a  new  directory  */ 
nkdir(name) 

char  name[]; 

{ 

int  pt,n .newfree; 

if (n=openf (nane,sysinp,rdfn) ) 

(closf(n); return  0;}  /*  nane  is  in  use  !  */ 

if  ( (n  =  creat.f  (name.sysinp)  )  =  =0)return  0;  /*  cannot  create  */ 
closf(n);  /*  got  the  name  entry,  close  it  */ 
pt=v/orkdir ; 

while(  loptr  rpt  ]  )pt=)  optr  [pt  ] ;  /*  nane  must  be  last  on  riir-list.  */ 
nev;free  =  loptr  Tfreptrl ;  /*  get  the  new  free  pointer  */ 

hiptr[pt]=-freptr ;  /*  link  on  a  cell  (-  to  indie  dir)  */ 

ptsfreptr ; 

f reptr  =  newf ree ;  /*  update  the  freptr  */ 

loptr[pt]=D;  /*  empty  dir  * / 

hiptr [ pt] =fregrp( ) ;  /*  and  the  directory  file  grp  itself  */ 
return  (grupio(hintr [pt ] , " ,\n" ,wr fn ) ) ;  /*  dir  contains  only  */ 
)  /*  i.e.  itself  */ 

/*  remove  a  directory-files  structure  */ 
rnfil(nane,flg) 
char  name[]; 
int  fig; 

{ 

int  n,i , preptr.pt, postptr; 

if ( (n=scndir(name) )==0)return  0;  /*  in  the  dir?  */ 
i =n ; 

— i ; 

if (i  =  =0)ret,urn  0;  /*  dont  allow  rmfil(’!.",x)  */ 


52 

138 


Dr.  Dobb’s  Journal,  Number  77,  March  1983 


preptr=workdir ;  /*  and  go  to  the  ] ink  before  the  entry  */ 

while  ( — i)preptr=loptr[preptr1; 

pt=loptr [preptr ] ;  /*  the  entry  */ 

postptrrloptrTpt] ;  /*  and  the  one  after  */ 

if  ( (hiptrfpt  ]  <0  )?,  ( fig!  =  1  ))  return  0;  /*  remove  dir?  */ 

if (rnname(n)==0)return  0;  /*  now  remove  the  n  th.  name  */ 

loptrT preptr  ]  =postpt.r  ;  /*  link  around  */ 

loptr[pt]=0;  /*  and  terminate  to  restrain  'remove'  */ 

remove ( pt ) ; 

return  1 ; 

} 

/*  remove  the  n  th.  name  from  the  work  directory  */ 
rmname(n) 
int  n; 

{ 

int  obuf ,ibuf ,ounit,iunit,l .wrtflg; 
char  c; 

wrtflg=obuf =dunit=ounit=0; 

whiled)  /*  but  only  used  for  one-pass  flow  control  V 

{ 

if ( ( ibuf =al loc ( ) ) ==0 )return  0; 
i f ( (obuf  =  alloc ( ) )  =  =0 ) break ; 
if ( (iunit=openit( 1 , ibuf , rdfn) )==0) break; 
if ( (ounit=openit( 1 , obuf ,wrfn) )==0) break; 

1=1  ; 

wrtflg=1 ;  /*  writing  flag  */ 

while(c=getc( iunit) ) 

{ 

if (n==l)wrtflp=0;  /*  suppress  this  entry?  */ 
if (wrtflg)putc (c ,ounit ) ; 
if(c==eol){++l;wrtflg=1 ; } 

} 

putc (0 , ounit ) ; 
wrtf lg=1 ; break ; 

} 

closf(iunit);closf(ounit);dalloc(ibuf);dall oc(obuf ) ; 
return  wrtflg;  /*  will  be  0  on  an  error  */ 

} 

/*  recursive  remove  of  dir-file  structure  */ 
remove ( pt ) 
int  pt; 

{ 

int  newfree; 

while(pt)  /*  down  the  dir  list  */ 

{ 

if (hiptr [ pt ] <0 )remove( (-hiptr Tpt 1 ) ) ;  /*  if  a  dir  */ 

else  fref il (hiptr [pt ] ) ;  /*  or  if  a  file  */ 

newfree=pt;  /*  now  add  this  loptr. hiptr  to  free  list  */ 

pt=loptr [pt] ;  /*  pt  onto  next  in  list  */ 
loptr[newfree]=freptr ;  /*  link  on  the  old  free  list  */ 
freptr=newfree ;  /*  and  update  the  free  pointer  * / 

} 

} 

/*  return  the  addr  of  the  next  free  top  blk  of  mem  r/ 
alloc ( ) 

{ 

int  blk; 

blk=rnaxblk  :  (Continued  on  next  page) 
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Small-C  Operating  System  (Listing  continued,  text  begins  on  page  36) 


while(blk) 

if(blkfree( — bib)  )  break ; 
fixblk(blk);  /*  fix  this  block  */ 
return  (hlk<<9);  /*  and  return  the  addr  */ 

} 

/*  fix  a  block  of  men  for  use,  given  the  block  no  */ 
fixblk(blk) 
int  bib; 

{ 

int  bits.words; 

words=blk>>4 ; 

bi  ts  =  bl k-( words <<tJ ) ; 

bits=-(1 +( 1 <<bits) ) ;  /*  complement  for  mask  */ 

mennap[ words  1 = hi tsRmemnapf words] ; 

} 

/*  is  the  given  block  number  free  ?:  returns  1  if  true,  else  0  */ 
blkfree ( blk ) 
int  blk; 

{ 

int  bits.words; 

words  =  blk>>ft ; 

bits  =  blk-(words<<i( ) ; 

return  ( ( 1  <<bitsM(memmap[words] ) ) ; 

) 


/*  free  up  the  given  block  corresponding  to  the  given  nddr  */ 
dal loo ( addr ) 
int  addr; 


t 

i 

int  bits, words, blk; 

addr=3??67&(addr>>1 );  /*  take  care  to  mask  * / 

blk  =  addr>>9 ;  f*  and  then  calc  the  blk  no.  */ 

if (blk==n)return;  /*  trap  */ 

words  =  blk>>Ji ; 

bits=blk-(words<<4 ) ; 

nemmap[words]=nenmap[words] ! ( 1 <<bits) ; 

} 

/*  return  the  location  of  a  directory  structure  */ 
dirfn(arg) 
int  arg; 

{ 

if (arg==D )return  glinks; 
i f (arg==1 )return  loptr; 
if  (arg==?  )return  hiptr; 

} 

inehar  ( ) 

{ 


char  c; 

c=conin();  /*the  machine  code  char  input  */ 

if(c>='  ' )outchar (c) ;  /*if  not  a  control  char  */ 
if (c==1 3)return  outchar ( eol ) ;  /*  carr-ret  to  eol  */ 
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if  (0  =  =*!  )return  0;  /*  control-d  ret  null  */ 

return  c; 

} 

outchar ( c ) 
char  c; 

{ 

if (c  =  =eol )conout ( 1  3 ) ;  /*  insert  a  carriage  return  if  eel  */ 

return  (conout(c)); 

} 

//include  shlibr.c 

/*  this  library  is  simply  the  routines  cegchar-cmpbcde  from  DPJ  '18  */ 


Listing  Two 

/*  initialize  stack,  i/o  and  hardware  etc.  */ 
inits ( ) 


int  i ; 

//asm 

mvi  a,0c3h  ;fix  up  the  system  call  location  at  zero 
sta  0 

Ixi  h, system 
shld  1 

lxi  h, system-4 

pop  b  ;the  local  variable  ' i ' 

pop  b  ;and  the  return  addr 

sphl 

push  b  ;the  return  addr 

push  b  ;and  'i' 

//endasm 

stdin=stdout=0;  /*  std  in,  out  via  console  */ 

i =8 ;  /*  now  book  up  all  memory  */ 

while ( i )nemmap[ — i ] =0 ;  /*  and  free  up  user  area  */ 

i rmaxblk ; 

while/ — i )dalloc ( i<<9 ) I  /*  leaves  zero  block  not  free  */ 


i=0; 

while(++i<max units ) prw[ i ] =n ; 

loptr  [0 ]=hiptrro  ]  =  gl  inks [0 ]=0;  /*  trap  errors 

} 


/* 

pet/put 

a 

group 

to 

disk 

*/ 

/* 

to/f  rom 

a 

given 

dma 

address 

*/ 

/* 

returns 

1 

if  o.l 

\r 

*  •  t 

D  if  error 

*/ 

/'define  sec 

t 

rk  26 

/*  26  by 

128 

byte  sectors  per 

/* 

conversions 

in 

the  next  section 

/*  assume  a  112  byte  bufsiz  ! !  ! 
g rupioC group, addr, io) 
int  group, addr, io; 


*/ 


track  */ 
*/ 

*/ 


int  track , sector ,nemad ; 
if (p,roup  =  =0)return  0; 
track= (group<<1 )/1 3; 

sector= (group<<2 )-track*26 ;  /*  0  to  21  range  not  1  to  26!  */ 

/#****  insert  routines  to  read/write  4  sequential  sectors  #**#**/ 

}  (Continued  on  next  page) 
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Small-C  Operating  System  (Listing  continued,  text  begins  on  page  36) 

The  following  routines  are  sone  programs  to  get  the  system  going. 

The  first  is  'save'. 

/*  Save  a  specified  number  of  blocks  of  memory  into  a  specified  file  */ 
/*  The  blocks  of  memory  are  assumed  to  start  at  2160  (rv\noM)  */ 

//define  bufsiz  r>1P 
char  buff [bufsiz] ; 
na i n ( ar gc , a  r gv ) 

int  argctnrp,v[  ] ; 

{ 

int  unit , ngrp , grp , addr ; 

if (argc!=3) {puterr ( "\nWrong  no.  of  args" ); return ; } 
if((unit=creatf(argv[11,buff))==0) 

{puterr ( "XnCannot  open  f ile" ); return ; } 
if((ngrp=todee(nrgvrP]))==0){puterr( "\nHow  many  blocks?" ); return ; } 
addr=?5f0;  /*  first  location  saved  */ 

while (ngrp — ) 

{ 

move(addr .buff ) ; 

if  (write  f  (unit )  ==0 ){ puterr  (  "Nn'Jrite  error" );  return ; } 
addr=addr+bufsiz ; 

} 

closf (unit) ; 

puterr("\nSuccessful  save"); 

} 

/*  move  a  buffer  in  memory  */ 
move( from, to) 

char  from[ ] , to[ ] ; 

{ 

int  k; 
k=0; 

while(k<bufsiz) 

to[k] =from[k++] ; 

} 

/*  convert  a  string  to  an  integer:  return  0  on  error  */ 

/*  routine  straight  from  small-c  compiler  */ 
todec( str ) 

char  str[]; 

{ 

int  k,n,c; 
n=k=0; 

while(c=str[k++]) 

{ 

c  =  c-  '0 ' ; 

if ( (c<0) | (c>9) )return  D; 
n=1 0*n+c; 

1 

return  n; 

} 

,  /'include  syslib.c 
End  of  program. 

This  program  'rm'  enables  the  removal  of  files; 

It  is  set  up  so  as  to  be  not  able  to  remove  directories. 

/'include  syslib.c 
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main(argc,argv) 

int  argc.argvT}; 

{while( — argc)rmf il (argvfargc] , 0) ;  } 

Fnd  of  program. 

The  next  program  is  'stats'. 

/*  Hives  statistics  of  number  of  free  dotted  pairs  and  groups  left  */ 

/*  Tf  any  arguments  are  given  it  will  give  the  size  of  these  files  V 
^include  syslib.c 
main ( argc , argv) 

int  argc,argv[]; 

{ 

int  pt ,n ,i , glinks [ ] , loptr T ] , hiptr [  ] ; 
gl inks=dirfn (0 ) ; 
loptr=dir fn ( 1 ) ; 
hiptr=dirfn(2 ) ; 
i  =  1 ; 

while(i<argc)  /*  for  any  given  file  names  */ 

{ 

if((n=scndir(argv[il) )==0) continue; 
pt=3optr[3l;  /*  the  working  dir  ptr  */ 

while( — n)pt=loptr[pt];  /*  go  to  the  files  dotted  pair  *7 
pt=hiptr [pt] ;  /*  a  pointer  to  the  file  */ 

if (pt>0) 

{ 

n=size (pt , glinks) ; 

if (n<0 )puts ( "  corrupted  file  structure  in  "); 
else  [outdec  (n ) ;  puts  ( "  groups  in")-;} 
puts (argv T i++] ) ; puts ( "\n" ) ; 

} 

} 

pt=hiptr [ 1 ] ; 

n=size(pt,loptr) ;  /*  find  the  no.  of  free  nodes  */ 

if (n<0)puts("  free  node  list  is  corrupted\n" ) ; 
else  outdec(n) ;puts("  free  nodes  left\n"); 
pt=hiptr[2]; 

n  =  s.ize (pt , glinks ) ;  /*  find  the  no  of  free  grps  left  */ 
if (n<0 )puts( "\n  free  group  list  is  corruptedNn" ) ; 
else  outdec(n) ;puts("  free  groups  left\n"); 

} 

sizeCpt, array) 

int  pt,array[ ] ; 

{ 

int  n ; 
n=0; 

wh i 1 e ( pt ) 

{ 

pt=array[pt] ; 

if(++n>8?000){n=-1 ; break;} 

} 

(Continued  on  next  page) 
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Small-C  Operating  System 

(Listing  continued,  text  begins  on  page  36) 


return  n; 

} 

puts(str ) 

char  sfcr[ ] ; 

( 

int  k ; 
k=0; 

while ( putchar (str Tk++] ) ) ; 

] 

outdec  ( nun;) 
int  num; 

{ 

int  k,zs; 
char  c; 
zs=n ; 

k=inoon; 

if (nun<0 ) {num= (-nun) ; putchar (  '  - ' ) ;  ) 
uhile(k>=1  ) 

( 

c=nun/k+  'O'; 

i f ( ( c !  =  1 0 ' ) ! (k=  =  1  )  '  ( zs ) ) 
fzs  =  1 ;putchar(c);  } 
num=nun7k ; 
k=k/10; 

} 

} 

/*  library  for  snall-c  system  programs  */ 
//asm 

sys  equ  0 
/'endasn 

/*  some  definitions  */ 

(/define  rdfn  1  /*  file  read  function  */ 

/'define  wrfn  ?  /*  write  function  */ 

/'define  apfn  3  /*  and  append  */ 

/'define  bufsiz  51? 

/'define  eol  10 
puterr(str ) 

char  str(]; 

{ sys  (0 ,  st.r  ,0,0);  } 
retchar ( ) 

fsys(1, 0,0,0);  ) 
putchar ( c ) 
char  c; 

{ sys (?, c , 0, 0) ;  ) 
pete (unit) 

int  unit; 

fsys ( 1 , unit , 0, 0) ;  ) 
putc(c.unit) 
char  c; 
int  unit; 

{sys (? , c .unit , 0) ; } 


readf (unit) 
int  unit; 

{sys (3, unit, 0,0); } 
writef (unit) 
int  unit; 

{sys ('I, unit, 0,0);  ) 
openf (name, buff , fn) 

char  name[ ] , buff [ ] ; 
int  fn; 

{sys (5 , name , buf f , fn ) ; } 
creatf ( name , buf f ) 

char  name[ ] , buf f [ ] ; 

{sys (6 , name , buf f , 0) ; } 
closf (unit) 
int  unit; 

{sys(7, unit, 0,0) ;  } 
readr (unit.n) 
int  unit.n; 

{sys (3, unit ,n ,0) ; } 
writer(unit.n) 
int  unit.n; 

{sys (9 , unit ,n , 0) ; } 
sendir (name) 

char  name[l; 

{sys ( 1 0, name ,0,0);) 
chdir (name) 

char  namoN; 

{ sys (11, name, 0, 0) ; ) 
mkdir(name) 

char  namefl; 

{sys ( 1 ?, name ,0,0);) 
rmfiKnarne.flg) 
char  naneM; 
int  f 1 c ; 

{sys ( 1 3, name , f 1r, 0) ; ) 
al loc ( ) 

{ sys (1 'l, 0,0,0);  ) 
dalloc(addr) 
int  addr; 

{sys(15,addr,Oto);  } 
dirfn(arp) 
int  arg; 

{sys ( 1 f.arg, 0, 0) ; } 
gosys ( ) 

{ sys (17,0,0,0); } 

/'asm 

; fetch  a  single  byte  from  the  address  in 
hi  into  hi  The  routines  are  as  in  DPJ  '!?• 
hut  only  the  routines ' ccgchar '  to  'empbede' 

/'endasm 

End  Listing 
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6809  Threaded  Code 

Parametrization  and  Transfer  of  Control 


High-level  languages  of  the  Forth  type 
-  now  proliferating  like  the  rabbits 
that  inspired  creation  of  Fibonacci 
numbers  —  are  usually  not  compiled  to 
machine -language  “object”  code.  Their 
more -or- less  humanly  intelligible  source 
code  gets  translated  by  a  text-interpreter 
program  into  an  intermediate  code  (“int- 
code”),  a  compact  sequence  of  memory 
addresses  (that  point  to  a  block  of  ma¬ 
chine  code)  and  parameters.  This  gets 
executed  by  an  inner  interpreter  program 
that  transfers  control  successively  to  the 
machine-code  blocks,  “threading”  them. 
An  example  of  a  Z80  inner  interpreter  is 
given  on  p.  29  of  the  book  by  Loeliger 
(1981),  who  comments  (pps.  36-7)  on  the 
timing  inefficiency  of  threading.  The  over¬ 
head  timing  loss  of  executing  a  “primitive” 
command  (defined  by  a  machine-code 
block)  is  76  cycles,  while  a  “secondary” 
command  (defined  by  an  intcode  se¬ 
quence,  a  de  facto  subroutine)  costs  268 
extra  cycles  for  the  transfer  of  control. 
This  must  be  why  the  fastest  version  of 
Forth  in  the  benchmark- comparison 
study  of  Gilbreath  (1981)  ran  six -fold 
slower  than  the  truly-compiled  PL-I/80 
or  Whitesmith’s  C  (all  on  a  Z80  system). 

The  recent  evolution  of  Forth-like 
HLLs,  facilitated  by  newer  CPUs  with 
superlative  addressing  power,  has  altered 
the  threading  mechanism  in  order  to 
minimize  timing  losses.  In  the  Z8000 
Forth  system  of  Odette  ( DDJ  No.  71) 
each  primitive  machine-code  block  is  ter¬ 
minated  by  two  machine-code  instruc¬ 
tions  (4  bytes,  18  cycles)  that  cause  a 
jump  to  the  next  primitive  in  the  intcode 
sequence,  so  that  a  sequence  of  primitives 
“runs  itself.”  Even  if  the  next  command 
is  a  secondary,  transfer  of  control  to  its 
intcode  sequence  is  expedited  by  prefacing 
that  with  a  machine-code  CALL  COLON 
(4  bytes,  10  cycles,  plus  35  cycles  execu¬ 
tion  time  for  the  COLON  subroutine). 
Since  the  terminal  return  to  the  main 
intcode  sequence  by  the  SEMI  command 
costs  25  cycles,  the  total  timing  penalty  is 
70  cycles.  Relative  to  the  Z80,  this  is  a 
four- fold  reduction  in  timing  loss,  at 
the  cost  of  two  more  bytes  added  to  each 
command. 
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The  purpose  of  this  note  is  to  de¬ 
monstrate  that  the  Motorola  6809  can 
“thread”  intcode  with  even  greater  effi¬ 
ciency,  since  its  instruction  set  is  rich  in 
both  direct  and  indirect  indexed  auto¬ 
increment  codes.  If  the  design  makes  use 
of  its  Y-index  register  as  the  equivalent 
of  a  CPU  program  counter,  terminating 
each  primitive  machine- code  block  by 
JMP  (,Y++)  will  cause  a  transfer  of  con¬ 
trol  to  the  next  primitive  in  the  sequence 
at  a  cost  of  only  two  bytes  and  nine 
cycles.  These  powerful  addressing  modes 
also  allow  what  I  call  “in-program  para¬ 
metrization”  of  any  intcode  command.  A 
simple  example  would  be  DROP  (n),  a 
command  to  “drop”  n  bytes  from  the 
data  stack  (using  the  U  register  as  the 
stack  pointer).  The  parentheses  signal  the 
text-interpreter  to  add  the  numeric  n 
directly  to  the  intcode  sequence,  following 
the  execution  address  of  DROP.  The  code 
for  the  parametrized  DROP  would  be: 

DROP  LDB  ,Y+  (load  binary  n  from 
program  into  B  register) 

LEAU  B,U  (reset  U  stack  pointer 
by  adding  n) 

JMP  (,Y++)  (jump  to  next 
intcode  command) 

This  generalized  command  executes  in  20 
cycles  for  any  value  of  n  from  1  to  127. 
The  “reading”  of  the  parameter  also  ad¬ 
vances  the  Y  counter  to  point  to  the  next 
command  in  the  sequence.  A  similar  para¬ 
metrization  in  conventional  Forth  would 
be  less  efficient,  being  sourced  as  n  DROP 
but  intcoded  as  5  (instead  of  3)  consecu¬ 
tive  bytes:  LIT  address,  n,  DROP  address. 
Execution  of  LIT  would  (a)  pick  up  n 
from  program,  and  (b)  save  it  on  the  data 
stack.  Execution  of  DROP  would  (c)  re¬ 
trieve  n  from  the  data  stack,  and  (d)  use 
it  to  reset  the  stack  pointer.  Steps  (b)  and 
(c)  are  clearly  a  waste  of  time.  There  is  no 
need  for  a  parameter  that  pertains  exclu¬ 
sively  to  one  command  to  visit  the  stack 
at  all!  The  stack  exists  to  save  data  gener¬ 
ated  by  a  command  for  use  by  a  subse¬ 
quent  command;  mere  copying  from  the 
program  is  not  generation  in  this  sense. 

In-program  parametrization  would 
likewise  simplify  the  intcode  and  speed 
up  execution  of  the  DO  .  .  .  LOOP  con¬ 
struct.  I  shall  illustrate  this  for  Loeliger’s 
CDO  .  .  .  CLOOP  since  this  variant  is  more 
efficient  for  loop  indices  from  0  to  255. 
For  generality,  I  also  make  the  loop- 
increment  (z)  explicit,  since  this  adds 
only  one  byte  to  the  intcode  and  only 
three  cycles  to  loop  timing,  and  it  avoids 


cluttering  up  the  dictionary  with  distinct 
CLOOP  and  +  CLOOP  commands.  The 
source  code  is  CDO  (n  m  i)  .  .  .CLOOP, 
where  n  and  m  are  the  initial  and  terminal 
indices  of  the  loop.  Here  the  6809  S  stack 
serves  as  the  “return”  stack. 

CDO  LDA  ,Y  (pick  up  n  from  pro¬ 
gram  into  A  register) 

LEAY  3,Y  (increment  Y  to  ad¬ 
dress  of  first  in-loop  command) 
PSHS  Y,  A  (save  address,  then  n, 
in  S  stack) 

JMP  (,Y++)  (jump  to  first 
in-loop  command) 

This  executes  in  26  cycles.  Note  that  n  is 
stacked  because  its  value  will  be  incre¬ 
mented  during  looping.  The  constants,  m 
and  i,  can  easily  “read”  by  offsets  using 
the  stack -stored  address. 

CLOOP  LDX  1,S  (pick  up  stored  address 
into  X  index -register) 

LDD  -2,X  (pick  up  m  and  i  into 
registers  A  and  B) 

ADDB  ,S  (add  i  to  the  stack- 
stored  n  ) 

STB  ,S  (save  i  +  n ,  as  new  value 
of  n) 

CMPA  ,S  (compare  m  to  new  n) 
BLS  EXIT  (if  m  is  less  or  same, 
exit  from  loop) 

LEAY  2,X  (move  X  plus  2  into 
Y) 

JMP  (,X)  (and  jump  back  into 
loop) 

EXIT  LEAS  3,S  (reset  S  stack  pointer 
before  exit) 

JMP  (,Y++)  (and  jump  to  post¬ 
loop  command) 

This  more  complex  transfer  of  control 
costs  40  cycles  for  each  run  of  the  loop. 
Comparison  with  other  systems  would  be 
tedious  since  timing  information  is  never 
given,  but  I  would  be  surprised  if  an  equi¬ 
valent  Forth  +CLOOP  was  as  fast. 

Conventional  Forth  allows  use  of 
different  entry  points  into  a  complex 
machine-code  routine,  since  all  this  re¬ 
quires  is  creation  of  a  dictionary  “name” 
that  specifies  the  entry  address.  It’s  not 
clear  whether  multiple  entry  points  into  a 
complex  intcode  routine  are  also  possible. 
In  the  design  used  by  Odette,  only  one 
entry  can  exist  into  an  intcode  routine. 
Intcode-defined  commands  are,  to  the 
programmer,  just  “names”  indistinguish¬ 
able  from  those  of  primitives.  If  a  6809 
system  adopts  the  Odette  model,  the  ad¬ 
dress  of  each  secondary  points  to  a  3-byte 
machine-code  “leader”  that  is  followed 
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by  the  intcode  sequence.  This  is  a  JSR 
COLON  (8  cycles)  that  pushes  the  address 
of  the  first  intcode  command  in  the  se¬ 
quence  onto  the  S  stack,  not  as  a  return 
address  but  for  use  by  the  COLON  rou¬ 
tine: 

COLON  LDX  ,S  (load  new  intcode 

address  from  stack  into  X 
register) 

STY  ,S  (save  old  intcode  address 
in  same  location  for  return) 

LEAY  2,X  (move  X  plus  2  into 
Y) 

JMP  (,X)  (and  start  running 
new  intcode) 

This  takes  24  cycles,  so  the  total  entry 
timing  loss  is  32  cycles.  Note  that  if  the 
first  two  instructions  were  PULS  X  and 
PSHS  Y  the  unneeded  resettings  of  the 
stack  pointer  would  add  three  cycles. 
However,  resetting  of  the  stack  pointer  is 
needed  in  coding  the  SEMI  command, 
which  terminates  the  secondary  sequence 
and  transfers  control  back  to  the  original 
sequence: 

SEMI  PULS  Y  (restore  old  intcode 
address  from  stack  into  Y) 

JMP  (,Y++)  (and  return  to 
running  that  intcode) 

Since  this  takes  1 6  cycles,  the  total  over¬ 
head  of  this  form  of  high-level  subroutine 
is  48  cycles  —  nearly  four  times  longer 
than  the  machine-code  JSR/RTS.  It  seems 
that  the  tradeoff  for  the  conciseness  of 
intcode  is  a  several-fold  slower  execution 
time! 

Entry  to  any  execution  address  with¬ 
in  a  complex  intcode  sequence  becomes 
possible  if  one  creates  a  JSUB  primitive, 
that  must  be  followed  by  the  “name”  of 
the  desired  entry  address  (added  to  the 
sequence  by  the  text-interpreter). 

JSUB  LDX  ,Y++ (load  “name”  address 
into  X,  set  Y  to  return  address) 

PSHS  Y  (save  return  address  in  S 
stack) 

LEAY  2,X  (move  X  plus  2  into 
Y) 

JMP  (,X)  (and  start  running 
“name”  intcode  routine) 

Execution  time  is  28  cycles,  only  four  cy¬ 
cles  less  than  the  single-entry-point  logic, 
and  the  “call”  adds  two  bytes  to  the  ori¬ 
ginal  intcode  program.  The  SEMI  return 
works  as  before.  Intcode-defined  com¬ 
mands  must  be  “marked”  so  the  text  in¬ 
terpreter  will  recognize  that  they  must  be 
preceded  by  JSUB.  Beyond  the  potential 
advantage  of  using  segments  of  a  complex 
intcode  sequence,  there  is  forced  recogni¬ 
tion  by  the  programmer  that  use  (and 
especially  nesting)  of  JSUB  degrades 
timing. 

One  of  the  intriguing  possibilities  of 
in-program  parametrization  is  in-line 
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insertion  of  a  machine- code  sequence 
within  an  intcode  sequence.  The  shift 
would  be  enabled  by  an  MCODE  primi¬ 
tive,  defined  by  a  simple  2-byte,  3-cycle 
JMP  ,Y,  that  will  transfer  control  to  the 
first  machine-code  byte.  The  machine- 
code  sequence  must  be  terminated  by  a 
JSR  SEMI,  which  will  transfer  control  to 
the  following  intcode  sequence,  at  a 
24-cycle  cost,  for  a  total  cost  of  5  bytes 
and  27  cycles.  This  would  allow  use  of 
special-purpose  operations  without  cre¬ 
ating  new  dictionary  entries  for  them,  but 
of  course  makes  the  program  system- 
dependent! 

The  extraordinary  flexibility  and 
user- extensibility  of  Forth-like  HLLs  is  a 
mixed  blessing,  since  it  encourages  cus¬ 
tomization  and  the  proliferation  of  dia¬ 
lects  almost  to  the  level  of  one-man  lan¬ 
guages,  the  classic  Tower  of  Babel  effect. 
However,  I  am  convinced  that  major 
conceptual  changes  (such  as  parametriza¬ 
tion)  are  inevitable  and  will  sooner  or 
later  be  quietly  adopted.  They  will  pro¬ 
vide  at  least  some  common  core  structure 
and  enhance  the  competitiveness  of  this 
linguistic  type.  Standardization,  to  what¬ 
ever  extent  possible,  should  be  deferred 
until  the  wealth  of  ideas  developed  in 
existing  dialects  can  be  pooled  into  an 
optimized  core.  That  is  how  a  science 
develops,  free  of  orthodoxy  and  sectari¬ 
anism,  always  ameliorable  by  common 
agreement,  never  proprietary.  It  should 
not  be  necessary  to  create  scores  of  fully- 
developed  rival  languages  such  as  STOIC, 
URTH,  SNAP,  or  the  new  RPL  of  Stryker 
(1982).  That  is  why  my  controversial  pro¬ 
posals  for  PARFOR  (DDJ  No.  52)  were 
purely  hypothetical  guidelines  for  possi¬ 
ble  improvement  of  the  linguistic  type, 
and  why  I  have  here  presented  only  a  few 
of  the  command  words  I  have  written  for 
my  6809  system.  If  they’re  not  optimal, 
they  ought  to  be  replaced  by  whatever  is. 
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A  Common-Sense  Guide  to 

Faster,  Smaller  BASIC 


Editor’s  note :  The  advice  in  this  article 
may  be  highly  interpreter-dependent.  As 
most  DDJ  readers  know,  the  inadequacies 
of  a  particular  interpreter  are  neither  uni¬ 
versal  nor  necessarily  long-lived.  In  the 
interest  of  readability  and  maintainability, 
many  people  deliberately  sprinkle  their 
code  liberally  with  the  very  “inefficien¬ 
cies”  pointed  out  here,  and  later  apply  a 
mechanical  compressor  (several  are  com¬ 
mercially  available,  with  varying  degrees 
of  thoroughness).  Thus,  two  versions  of 
each  program  can  be  kept  -  one  for  exe¬ 
cution  and  one  for  documentation. 


In  .hese  days  of  increasing  central  pro¬ 
cessor  speed  and  decreasing  cost  of 
memory,  it  is  perhaps  anachronistic  to 
speak  of  optimizing  speed  and  memory 
capabilities  of  your  microcomputer.  But 
assume  for  a  minute  that  your  home 
system  isn’t  a  Cray-1  with  a  couple  of 
megabytes  of  RAM  and  a  flock  of  14” 
Winchesters.  I  remember  just  twenty 
years  ago  when  the  best  military  com¬ 
puter  at  sea  (on  the  Polaris  program)  had 
a  main  memory  cycle  time  of  80  milli¬ 
seconds  —  yes,  milliseconds,  not  micro¬ 
seconds.  Running  real-time  navigation  for 
even  a  submarine  was  touch  and  go.  So 
we  put  eight  read/write  heads  on  one 
track  of  the  drum(!),  and  got  a  10  milli¬ 
second  (Wow!)  response. 

Well,  you’re  not  that  bad  off.  Let’s 
assume  your  home  system  is  a  Z-80  and 
you’ve  got  32K  of  RAM  using  a  12K 
BASIC.  You’ve  already  got  a  system  that 
is  fast  compared  to  the  Polaris  system, 
but  you’d  still  like  to  get  the  most  out  of 
it.  Here  are  some  of  the  ways  that  you 
can  do  that.  Obviously,  you  shouldn’t 
expect  that  every  one  of  these  methods 
will  improve  speed  and  minimize  memory 
usage.  Some  methods  may  do  both,  but 
most  will  do  one  or  the  other.  In  addition, 
some  of  the  methods  I  will  discuss  will 
improve  the  accuracy  of  your  results  — 
when  they  can  be  applied. 

First,  let  us  consider  speed  enhancing 
techniques.  Each  individual  application 
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may  appear  trivial,  but  overall  the  effect 
is  significant.  Try  some  of  the  examples 
and  you’ll  agree. 

(1)  Never  put  a  RfeM  statement 
in  the  middle  of  a  set  of  FOR-NEXT 
statements. 

Not  this: 

140  FOR  J=1  TO  10 
150  REM  **  THIS  IS  A  LOOP 
160  A=A+J 
170  NEXT  J 

But  this: 

140  REM  **  THIS  IS  A  LOOP 
150  FOR  J=1  TO  10 
160  A  =  A  +  J 
170  NEXT  J 

(In  the  first  example,  the  REM  statement 
would  be  read  ten  times;  in  the  latter, 
only  once.  The  more  times  the  loop  is 
iterated,  the  greater  the  time  savings.) 

(2)  Avoid  requiring  the  program  to 
process  a  REM  statement. 

Not  this: 

270  GOSUB  7000 

7000  REM  **  SUBROUTINE  ARCTAN 
7010  REM  **  ANGLE  IN  RADIANS 
7020  . . . 

But  this: 

270  GOSUB  7000 

6998  REM  **  SUBROUTINE  ARCTAN 

6999  REM  **  ANGLE  IN  RADIANS 

7000  . . . 

(In  the  first  example,  two  REM  state¬ 
ments  are  read  each  time  the  subroutine 
is  called.  In  the  second  example,  no  REM 
statements  are  ever  read  by  the  program; 
they  show  only  in  the  listing.) 

Not  this: 

500  REM  **  USER  INPUT 
5  1 0  INPUT  “NEXT  CHOICE”, U  $ 

520  IF  U$  =  “END”  THEN  END 

550  GOTO  500 
But  this: 

499  REM  **  USER  INPUT 

500  INPUT  “NEXT  CHOICE”,U$ 

510  IF  U$=“END”  THEN  END 

540  GOTO  500 

(In  the  first  example,  the  REM  statement 
is  read  each  time  the  program  is  returned 
to  the  user  input  by  Line  550.  In  the 
second  example,  the  REM  statement  is 


ready  only  once  in  the  normal  course  of 
the  program.) 

(3)  Use  special  symbols  in  lieu  of 
blank  lines  to  call  attention  to  REM  state¬ 
ments. 

Not  this: 

160  NEXT  J 
170  REM 

180  REM  FUNCTION  TO  BE 
PLOTTED 
190  REM 

200  FND(X )  =  4*X*X  +  P1 
But  this: 

160  NEXT  J 

170  REM  **  FUNCTION  TO  BE 
PLOTTED 

180  FND(X)  =  4*X*X  +  P1 

(In  the  first  example,  three  REM  state¬ 
ments  must  be  read  by  the  program.  In 
the  second  example,  only  one.) 

(4)  Keep  REM  statements  as  short  as 
practicable. 

Not  this: 

740  REM  **  THIS  IS  A  SUBROUTINE 
TO  EXTRACT  THE  INVERSE 
TANGENT  FUNCTION 

But  this: 

740  REM  **  SUBROUTINE  ARCTAN 

(In  the  first  example,  the  program  must 
read  a  much  more  lengthy  statement, 
even  though  it  is  ignored  in  processing.) 

(5)  Minimize  display  length,  amount, 
of  input,  and  input  processing  for  inter¬ 
active  programs. 

Not  this: 

210  INPUT  “HOW  MANY  OBSERVA¬ 
TIONS  DO  YOU  WANT  TO 
ENTER”, E2 

But  this: 

210  INPUT  “NUMBER  OF 
SAMPLES”, E2 

Not  this: 

1430  INPUT  “NEW  GAME”, U$ 

1440  IF  LEFT$(U$,1)  =  “Y” 

THEN  230 

1450  IF  LEFTS (U $,1)  =  “N” 

THEN  END 
1460  GOTO  1430 
But  this: 

1430  INPUT  “NEW  GAME  (Y/N)”, US 
1440  IF  U$  =  “Y”  THEN  230 
1450  IF  US  =“N”  THEN  END 
1460  GOTO  1430 

(The  less  time  spent  printing  unneeded 
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displays  and  typing  unneeded  letters,  the 
faster  the  operation  goes.) 

(6)  Assign  a  symbolic  name  for  fre¬ 
quently  used  constants. 

Not  this: 

760  A1  =  3.141592654 *R1  *R1 
770  A2  =  3. 1415926  54*R2* R2 

But  this: 

760  PI=3. 141592654 
770  A1  =  PI  *  R1  *R1 
780  A2=PI *  R2  *  R2 

(The  interpreter  reads  a  numerical  con¬ 
stant  character  by  character  each  time  it 
is  encountered.  A  constant  stored  as  a 
symbolic  is  read  character  by  character 
only  once,  and  as  a  stored  value  sub¬ 
sequently.) 

(7)  Use  simple  variables  (A,  B,  C,  etc.) 
or  nonsubscripted  variables  (A7,  B4,  C9, 
etc.)  in  lieu  of  subscripted  variables  [A(l), 
B(2,3),  C(4),  D(8,l),  etc.]  whenever  pos¬ 
sible.  (Subscripted  or  array  variables 
generally  require  more  manipulations  to 
store  and  retrieve,  hence  take  longer.) 

(8)  Avoid  the  use  of  transcendental 
functions  (trig,  logs,  exponentiation) 
whenever  possible.  For  integral  powers, 
use  repeated  multiplication. 

Not  this: 

540  X=YA2 
But  this: 

540  X=Y * Y 

(Trigonometric  functions  can  be  most 
time  consuming.  Raising  a  number  to  a 
power  requires  both  LOG  and  EXP  func¬ 
tions,  lengthy  operations,  hence  should 
be  avoided  for  integer  powers.) 

Now  let  us  turn  our  attention  to 
techniques  which  reduce  memory  require¬ 
ments.  It  is  not  surprising  that  some  of 
the  speed  enhancing  techniques  also  re¬ 
duce  memory.  Specifically,  (3)  through 
(7)  above  reduce  memory  requirements. 
There  is  a  version  of  (3)  which  is  particu¬ 
larly  wasteful  of  memory;  one  involving 
the  usfe  of  multiple  REM  statements  to 
outline  the  program  title,  author’s  name, 
copyright  statement,  etc.,  with  rows  and 
columns  of  asterisks  or  other  symbols. 
Each  of  the  symbols  and  spaces  is  indivi¬ 
dually  stored  in  memory  —  and  that  takes 
a  lot  of  memory  for  little  real  benefit. 

Most  of  the  prior  examples  are  obvi¬ 
ous  as  to  the  reason  for  the  saving,  but  a 
couple  require  explanation.  In  (6),  added 
memory  is  needed  during  operation  to 
store  the  value  of  the  constant  symbol  — 
but  program  memory  is  saved  since  multi¬ 
ple  symbols  and  not  multiple  values  are 
listed  in  program  storage.  In  (7),  the 
saving  in  using  nonsubscripted  variables 
lies  in  elimination  of  the  storage  for  the 


array  definition  and  its  addresses.  These 
overhead  functions  are  not  needed  for 
individual  variables. 

There  are  other  memory-saving  tech¬ 
niques: 

(9)  Do  not  overdimension  arrays. 
Many  systems  have  a  default  value  (e.g., 
10  or  10,10)  for  arrays  for  which  you 
have  not  written  a  DIM  statement.  It  may 
save  program  storage  to  not  dimension  a 
3  by  4  array,  but  when  you  accept  the 
default  1 0  by  10,  you  waste  an  equivalent 
storage  for  a  7  by  6  array. 

(10)  For  systems  allowing  multiple 
statements  per  line,  use  this  capability 
to  combine  short  statements.  The  colon 
or  other  separator  symbol  takes  less  stor¬ 
age  than  a  new  line  number.  Caution: 
Remember  that  most  systems  skip  all 
statements  to  the  right  of  an  IF-THEN  in 
a  single  line,  unless  the  IF  condition  is 
TRUE. 

(11)  If  your  system  allows,  use  the 
INPUT  with  PRINT  capability. 

Not  this: 

230  PRINT  “LENGTH  OF  SIDE” 

240  INPUT  LI 

But  this: 

230  INPUT  “LENTH  OF  SIDE”, LI 

(The  latter  has  limits,  however.  You  can¬ 
not  insert  a  variable  inside  the  INPUT 
with  PRINT  format.) 

(12)  If  your  system  allows  variable 
string  lengths,  set  STRING=  to  the  lowest 
value  that  will  encompass  the  strings  you 
plan  to  use.  This  is  especially  important 
with  arrays  of  strings  since  every  cell  in 
the  array  will  reserve  as  many  bytes  as 
STRING=  designates.  A  large  array  using 
the  default  value  for  STRING=  (18  bytes 
in  some  systems)  can  eat  up  a  lot  of 
memory. 

(13)  Avoid  isolated  statements  — 
ones  which  will  never  be  executed  be¬ 
cause  the  program  bypasses  them.  Every 
programmer  has,  at  one  time  or  another, 
introduced  unused  material  into  a  pro¬ 
gram.  A  subroutine  is  inserted,  but  never 
called.  A  GOTO  bypasses  one  or  more 
lines  of  the  program.  These  isolated  state¬ 
ments  waste  memory  and  should  be  de¬ 
leted.  They  most  frequently  result  from 
inadequate  review  after  a  program  has 
been  “patched”  or  rewritten. 

(14)  Lastly,  memory  can  be  saved 
by  eliminating  spaces  in  the  program. 
Caution:  Be  judicious  in  using  this  tech¬ 
nique,  even  if  you  only  have  a  small 
amount  of  memory.  A  statement  like: 

100FORI  =  ATOM  :LETJORK  =  TRUE: 

NEXTI 


could  possibly  blow  a  mental  fuse! 

So  far  there  has  been  no  discussion 
of  accuracy.  Only  one  of  the  techniques 
mentioned  so  far  has  an  influence  on 
accuracy.  In  (8)  avoidance  of  transcen¬ 
dental  was  discussed  to  enhance  speed. 
In  typical  BASIC  systems,  the  TRIG, 
LOG  and  EXP  functions  are  typically 
one  to  three  places  less  accurate  than  the 
arithmetic  functions  (+,  -,  *,  and  /).  Thus 
the  use  of  repeated  multiplications  in  lieu 
of  integer  powers  is  not  only  faster  but 
more  accurate. 

As  for  fractional  powers  and  the 
TAN/ARCTAN  functions,  in  most  cases 
one  uses  them  in  BASIC  and  accepts  the 
speed  and  accuracy  penalties.  If  one  must 
have  the  ultimate  in  accuracy  for  a  tran¬ 
scendental,  then  evaluation  of  a  truncated 
series  expansion  is  probably  the  best 
route.  However,  a  large  penalty  in  speed 
is  incurred,  since  the  series  methods  are 
usually  very  slow. 

From  the  foregoing  discussion,  we 
can  conclude  that  there  are  some  sure 
ways  to  approach  maximum  speed,  mini¬ 
mum  memory  use,  and  maximum  accu¬ 
racy.  Not  all  of  these  methods  can  be 
applied  all  the  time.  Some  methods  opti¬ 
mize  speed  and  memory,  others  optimize 
speed  and  accuracy,  but  none  optimize 
all  three. 
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GUEST  ESSAY 

A  Fundamental  Mistake 
in  Compiler  Design 


I  was  stunned  to  read  in  DDJ  that  the 
MSDOS  non-macro  assembler  requires 
53,000  bytes  of  object  code  and  the 
competing  CP/M-86  assembler  requires 
27,000  bytes.  1  can  only  echo  Dave 
Cortesi’s  comment,  .  .  this  kind  of 
bloat  is  inexcusable.” 

Something  is  radically  wrong.  The 
authors  of  these  assemblers  are  presumably 
competent  programmers.  The  past  records 
of  their  firms  certainly  indicate  this.  I  am 
sure  most  of  them  are  younger  and  smarter 
than  I.  The  problem  has  to  lie  elsewhere. 

In  pondering  this  problem,  I  soon 
recognized  that  assemblers  weren’t  the 
only  culprits.  In  fact  there  is  even  more 
bloat  in  the  typical  compilers  used  today. 
There  is  also  a  fundamental  reason  for 
this  bloating  all  down  the  line  in  typical 
software  and  the  reason,  I  believe,  is 
traceable  to  a  fundamental  mistake  that 
compiler  designers  have  been  making  for 
thirty  years. 

My  conclusions  are  not  based  on  a 
formal  scientific  proof.  They  are  simply 
inferred  from  common  sense  observations. 
With  that  caveat  I  will  first  discuss  bloating 
in  assemblers  and  then  turn  to  the  real 
culprit,  the  conventional  compiler. 

Assemblers 

The  state  of  the  art  for  the  object 
code  size  of  a  good  structured  program¬ 
ming  machine  code  assembler  with  all  the 
IF.  ..THEN,  IF.  .ELSE... THEN,  BEGIN 
. .  .UNTIL  constructs  one  needs  to  auto¬ 
matically  assemble  branch  instructions  is 
on  the  order  of  1500  to  2000  bytes.  The 
size  will  vary  depending  on  the  instruc¬ 
tion  set  of  the  processor  but  that  is 
roughly  what  one  should  expect. 

DDJ  published  an  excellent  example 
of  a  6502  assembler  by  W.  F.  Ragsdale 
in  the  September  1981  issue.  Ragsdale’s 
assembler  requires  only  1300  bytes  of 
object  code.  I  have  both  a  6502  and  an 
8080  assembler,  neither  quite  as  elegant 
as  Ragsdale’s  but  each  is  about  the  same 
size  and  power  as  his. 

Do  not  be  fooled  by  the  small  size. 
These  assemblers  are  every  bit  as  power¬ 
ful  as  the  best  bloated  assemblers  and 
much  more  convenient  to  use  simply  be¬ 
cause  it  is  practical  to  make  them  resident 
and  part  of  your  language.  You  can  assem¬ 
ble  and  test  a  machine  code  program  on 
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the  spot,  interactively,  without  leaving 
you  language.  I  do  this  routinely.  This 
would  not  be  practical  if  my  assembler 
took  53Kb  or  even  27Kb.  My  machine 
simply  isn’t  that  big. 

The  argument  that  since  memory  is 
so  cheap,  the  size  of  a  program  really 
doesn’t  matter  is  persuasive  but  false.  You 
pay  a  lot  more  than  the  price  of  additional 
memory  for  poor  programming.  You  pay 
in  time,  convenience  of  use,  i.e.  frustra¬ 
tion,  and  in  the  ability  to  understand, 
change  and  modify  the  program.  There  is 
a  world  of  difference  in  making  a  simple 
change  to  a  27Kb  program  as  compared 
to  a  2Kb  program.  Further,  a  little  bloat 
in  an  application  program  is  of  a  lot  less 
concern  than  bloating  in  the  assembler, 
compiler  and  other  basic  tools  of  compu¬ 
ting. 

The  state-of-the-art  assemblers  I  have 
mentioned  were  written  in  the  Forth  lan¬ 
guage  but  I  am  sure  equally  good  assem¬ 
blers  can  be  written  in  Pascal  or  any  other 
good  language,  if  someone  has  not  already 
done  so. 

Compilers 

How  big  should  a  compiler  be?  I 
counted  the  space  taken  by  the  compiler 
functions  in  my  Fig- Forth  system.  It  uses 
only  350  bytes! 

This  is  not  one,  but  two  orders  of 
magnitude  smaller  than  conventional 
compilers.  Whether  one  likes  the  language 
or  not  is  immaterial;  the  point  is  that  if 
this  is  all  it  takes  to  perform  the  compiling 
functions  of  a  powerful  language  (and 
Forth  is  a  very  powerful  language),  then 
what  is  wrong  with  conventional  compil¬ 
ers?  Where  are  they  making  their  mistake? 

If  the  compiler  of  your  favorite  lan¬ 
guage  were  reduced  in  size  to  500  or 
1000  bytes,  you  could  make  it  a  resident 
compiler  which  you  could  then  use  inter¬ 
actively.  Wouldn’t  that  be  nice?  You 
would  then  have  room  for  the  object 
code  produced  by  the  compiler  and 
wouldn’t  need  an  operating  system  to 
continually  swap  things  around. 

By  it  being  small,  the  compiler  would 
be  easy  for  you,  as  the  user,  to  understand 
and  change.  You  could  make  it  extensi¬ 
ble.  Just  think,  if  you  then  saw  some  fea¬ 
ture  you  liked  in  some  other  language, 
you  could  extend  your  compiler  to  in¬ 
clude  that  feature.  And  you  could  make 
the  extension  and  test  it  on  the  spot,  in¬ 
teractively,  until  the  language  was  perfect 
for  you.  You  wouldn’t  have  to  wait  for 
the  author  of  the  compiler  to  make  a  set 


of  changes  that  he  thinks  will  be  best  for 
you.  You  make  the  changes  that  are  best 
for  you.  Let  him  make  the  changes  that 
are  best  for  him.  I  call  a  small  compiler 
instant  computer  freedom. 

An  extensible  compiler  has  long  been 
a  goal  of  compiler  writers.  Most  books 
that  I  have  read  on  the  subject  begin  with 
a  syntax  definition  of  languages.  A  partic¬ 
ular  syntax  defining  a  language  is  then 
selected  and  most  of  the  book  explains 
how  to  implement  the  compiler  based  on 
the  chosen  syntax.  This  is  really  tough 
reading  so  I  turn  to  the  end  of  the  book 
where  I  can  usually  find  a  statement  to 
the  effect:  “  ...  so  that  is  how  you  write 
a  compiler.  Now  it  would  have  been  nice 
if  we  could  have  made  it  extensible  but 
that’s  simply  not  practical.  All  previous 
attempts  in  that  direction  have  resulted 
in  failure  .  .  .  .” 

Folks,  the  problem  of  designing  an 
extensible  compiler  does  not  lie  in  your 
techniques.  They  are  super.  The  problem 
lies  in  Chapter  1 : 

If  you  start  out  with  a 
complicated  syntax  for  a  language, 
you  will  end  up  with  a 
large  and  complicated  compiler. 

It  will  then  be  too  difficult  for  the  user  to 
extend. 

One  reason  Charles  Moore  was  able 
to  write  an  extensible  compiler  for  Forth 
is  that  he  started  out  with  a  very  simple 
syntax.  It  is  so  simple  that  it  can  be  writ¬ 
ten  in  a  few  lines: 

(1)  A  valid  character  is  any  member  of 
the  ASCII  character  set  except  the 
space  and  carriage  return. 

(2)  A  word  is  a  string  of  ASCII  charac¬ 
ters  delimited  by  an  ASCII  blank. 

(3)  A  line  is  a  sequence  of  words  termi¬ 
nated  by  either  the  ASCII  return,  the 
established  line  length,  or  a  0. 

(4)  If  a  word  in  a  line  is 

(a)  a  previously  defined  word,  it  is 
executed. 

(b)  not  a  previously  defined  word, 
then  it  must  be  either  a  number 
in  the  current  base  or  an  error. 

(1)  If  it  is  a  number,  it  is  placed 
on  the  stack. 

(2)  If  it  is  not  a  number,  it  is  an 
error. 

That’s  it.  The  language  is  expanded 
from  this  basic  syntax.  The  compiler 
starts  out  very  small  and  extensible  and  is 
kept  extensible.  Adding  the  syntax  of  the 
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usual  structured  programming  constructs 
-  IF. .  .ELSE. .  .THEN,  BEGIN. .  .UNTIL, 
DO  loops,  etc.  —  results  in  the  final  350 
byte  Fig- Forth  compiler  which  the  user  is 
free  to  expand  at  will. 

One  of  the  interesting  products  of 
Moore’s  approach  is  that  by  making  the 
compiler  small  and  extensible  right  from 
the  very  beginning,  it  appears  that  the 
language  can  be  extended  indefinitely. 
There  does  not  appear  to  be  an  upper 
bound  to  the  complexity  of  the  language. 
If  a  user  creates  a  syntax  that  appears  to 
box  him  in,  he  should  always  be  able  to 
leave  a  path  for  continued  expansion  in 
some  other  direction. 

There  may  be  other  simple  syntaxes 
that  will  lead  to  small,  powerful,  efficient, 
interactive,  extensible  compilers,  but  the 
syntax  used  by  Moore  is  known  to  work. 
It  also  may  turn  out  that  all  such  simple 
syntaxes  yielding  extensible  compilers  re¬ 
sult  in  languages  which  have  characteris¬ 
tics  quite  similar  to  Forth.  Personally  I 
think  that  would  be  just  great,  but  I  am 
sure  there  will  be  some  initial  objections 
simply  because  that  is  not  the  way  things 
have  been  done  for  the  last  thirty  years. 

For  example,  the  languages  may  con¬ 
sist  of  almost  all  verbs.  Although  you  can 
put  them  in  if  you  wish,  there  are  no  ex¬ 
pository  statements  in  Forth.  Every  word 
produces  an  action.  The  traditionalist 
who  has  been  taught  otherwise  may  say, 
“That’s  terrible  —  how  can  you  express 
yourself  in  a  gutteral  language  that  doesn’t 
have  elegant  expository  statements?” 

This  is  a  loaded  question  that  really 
has  three  answers: 

(1)  Of  course  you  realize  that  you  can 
get  the  computing  job  done.  That’s 
what  verbs  are  all  about. 

(2)  Do  not  confuse  program  documenta¬ 
tion  with  computing.  They  are  two 
separate  functions.  The  user  should 
not  be  forced  to  document  when  he 
feels  it  to  be  unnecessary  and  all  he 
wants  to  do  is  compute.  Of  course  it 
should  be  made  convenient  for  the 
user  to  document  to  his  heart’s  con¬ 
tent  if  that  is  what  he  wishes  to  do. 

(3)  The  real  answer  to  the  gutteral  lan¬ 
guage  charge  is  that  with  an  extensi¬ 
ble  language,  the  user  has  complete 
freedom  of  expression  simply  be¬ 
cause  he,  not  the  compiler  writer, 
controls  the  syntax  of  the  language. 
The  user  is  in  a  much  better  position 
to  decide  what  syntax  he  needs  or 
would  like  in  a  particular  application 
to  express  his  ideas  properly.  He  can 
try  out  a  particular  syntax  and  test  it 
immediately.  If  it  is  unsatisfactory, 
he  can  then  change  it.  The  guiding 
principle  is  that  since  the  bloat  in 
compilers  is  related  to  the  syntax,  it 
is  better  to  let  the  user  control  the 


syntax.  The  bloat  will  then  tend  to 
be  at  the  top  in  the  application  and 
not  at  the  bottom  where  it  hurts. 

All  this  talk  about  changing  the  com¬ 
piler  and  changing  the  syntax  must  seem 
quite  vague  and  mysterious  to  those  read¬ 
ers  who  have  not  had  the  opportunity  to 
actually  do  this  sort  of  thing.  It  isn’t.  Let 
me  try  to  explain  with  a  practical  example. 

Say  I  have  a  file  system  and  I  wish  to 
define  individual  record  components  in  a 
file  and  give  them  unique  names.  I  also 
want  to  fetch  and  store  the  record  com¬ 
ponents  without  having  to  remember 
their  data  type  or  their  offset  location  in 
a  record.  Let’s  call  the  fetch  and  store 
operators  V@  and  V!.  If  the  name  we  as¬ 
sign  to  a  record  component  is  xxxx,  then 
we  would  like  to  be  able  to  use  the  fol¬ 
lowing  syntax  for  fetching  and  storing 
data  for  xxxx  in  the  current  record: 

xxxx  V@  to  fetch  the  component 
xxxxV!  to  store  the  component 

If  the  data  type  of  xxxx  is  numerical, 
we  will  use  the  convention  that  V@  puts 
the  fetched  number  on  the  parameter 
stack.  If  its  data  type  is  string,  V@  will 
place  the  fetched  string  on  the  string 
stack.  V!  will  be  similarly  designed.  What 
we  are  trying  to  do  is  design  universal 
fetch  and  store  operators  that  receive  in¬ 
formation  on  the  component’s  data  type 
and  location  directly  from  the  name  of 
the  component. 

Once  a  protocol  is  set  up  as  to  how 
the  type  and  offset  information  is  to  be 
transferred,  the  design  of  V@  and  V!  is 
straightforward.  For  example,  xxxx  could 
leave  two  numbers  on  the  parameter 
stack  to  be  picked  up  and  used  by  the 
operators. 

The  compiler  change  comes  in  when 
we  try  to  define  xxxx.  We  could  use  the 
ordinary  compiler  to  define  xxxx  so  that 
when  it  is  executed  it  leaves  the  proper 
numbers  on  the  stack.  But  then  each  time 
we  encountered  a  new  component,  we 
would  have  to  tailor  its  definition  to  its 
data  type  and  its  offset.  Sooner  or  later 
we  would  foul  up  and  make  a  mistake. 
The  compiler  should  take  care  of  that 
sort  of  thing.  So  we  change  the  compiler. 

For  this  situation  I  added  several 
new  defining  words  to  the  compiler: 
INTEGER”,  BYTE”,  DINTEGER”,  and 
STRING”,  They  are  used  to  define  record 
components  in  the  current  file,  allocate 
space  in  the  file  records,  and,  when  the 
newly  defined  name  is  invoked,  pass  the 
proper  information  to  the  fetch  or  store 
operator.  It  was  not  very  difficult  to  do. 
It  was  all  done  in  one  session  and  the 
system  was  tested  interactively  without 
leaving  the  language. 

Now  when  I  execute 
STRING”  PARTNAME 


I  define  a  record  component  named 
PARTNAME  in  the  current  file.  If,  for 
example,  I  place  the  string  GIZMO  ONE 
on  the  string  stack  and  then  execute 

PARTNAME  V! 

the  string  GIZMO  ONE  will  be  placed  on 
the  disk  in  the  current  record  as  the  value 
of  PARTNAME.  Similarly  then  executing 

PARTNAME  V@ 

will  fetch  the  string  GIZMO  ONE  back  to 
the  string  stack. 

We  could,  of  course,  get  fancier  and 
have  the  new  compilers  also  link  the  new 
record  components  to  components  in 
other  files,  but  as  you  have  seen,  the 
ability  to  decide  on  a  syntax  change  and 
then  implement  that  syntax  by  modifying 
the  compiler  has  obvious  practical  uses.  It 
is  a  very  creative  form  of  endeavor  that 
pays  compound  interest  by  making  all 
subsequent  computing  easier. 
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OPEN  FORUM 

Comments  on 

“Fifth  Generation  Computers” 


Editor's  note:  The  good  Doctor  enjoys  seeing  dialogue  among 
the  readers.  Recently  we  received  the  following  piece  in  re¬ 
sponse  to  the  guest  essay  “Fifth  Generation  Computers"  by 
Richard  Grigonis  which  was  published  in  the  December  1982 
issue  of  DDJ.  It  provides  some  interesting  counterpoints 
which  seem  likely  to  interest  readers,  and  perhaps  to  gener¬ 
ate  more  comment  on  the  issues  discussed. 

I  admit  that  the  cost-performance  ratio  of,  say,  putting  an 
IBM  370  on  a  Motorola  68000  -  a  plan  which  IBM  is 
seriously  considering  —  should  spell  doom  for  at  least  the 
superminicomputer  manufacturers.  But  Richard  Grigonis,  in 
his  essay  “Fifth  Generation  Computers”  (DDJ  No.  74),  is  not 
just  talking  about  “microsuperminis”  or  even  “micromain¬ 
frames.”  He  asks  us  to  believe  that  a  supercomputer,  64-bit 
processor  running  at  110  megahertz  (which  is  essentially  a 
Cray  2S)  can  be  put  on  a  single  chip. 

It  will  take  a  while  for  VLSI  technology  to  catch  up  to 
mainframes  in  terms  of  performance  and  fault  tolerance  —  even 
mainframes  have  fault  tolerance  problems.  Redundant  circuitry 
must  always  be  built  to  take  care  of  such  things  as  processors, 
main  memory,  and  recovery  from  faults  in  the  I/O  system. 
Grigonis’  secondary  32-bit  I/O  processor,  probably  used  for 
maintaining  the  graphics,  would  itself  require  error  detecting 
circuitry. 

The  64-bit  main  microprocessor  would  have  to  be  so 
small  (in  order  to  achieve  110  megahertz)  that  Heisenberg’s 
Uncertainty  Principle  would  come  into  play,  and  the  posi¬ 
tions  of  the  electrons  in  the  signal  pathways  of  the  processor 
would  become  “blurred,”  leading  to  strange  field  effect  in 
neighboring  signal  pathways.  What  all  this  means  in  that  90% 
of  his  processor  would  have  to  consist  of  error- correcting 
circuitry. 

Granted,  slower  64-bit  processors  will  probably  be  in  use 
as  early  as  1986.  I  am  surprised,  however,  at  the  preciseness  of 
his  prediction  that  processors  of  110  megahertz  will  have  been 
developed  by  the  year  1992.  It  would  have  been  more  realistic 
to  suggest  a  barrier  of  1 00  megahertz  instead. 

The  gigantic  4-megabyte  EEPROMS  Grigonis  postulates 
may  in  fact  be  developed  by  1992,  but  probably  for  main¬ 
frames,  not  micros.  Even  today  the  most  advanced  micro  tech¬ 
nology  only  provides  the  main  memory  chips  used  in  main¬ 
frames.  The  microprocessor  arm  of  this  technology  has  been 
incorporated  in  mainframes  only  in  the  form  of  controllers 
and  intelligent  terminals.  Microprocessor  technology  cannot 
be  applied  to  mainframe  processors  because  of  logic  circuit 
“randomness”  problems  and  a  general  lack  of  performance, 
at  least  until  recently.  More  gates  than  those  projected  for 
future  microprocessors  would  be  required. 

Also,  mainframe  processor  gates  have  switching  times 
of  about  one  nanosecond,  as  opposed  to  the  three-  to  five- 


nanosecond  switching  times  of  the  best  microprocessors  such 
as  the  eight -megahertz  Z80-H  and  the  16-megahertz  version 
of  the  Motorola  68000.  The  Grigonis  64/110  processor  would 
probably  have  a  switching  time  of  about  half  a  nanosecond  — 
which,  coincidentally,  pushes  silicon  to  its  theoretical  physical 
limits.  I  don’t  think  a  single  chip  made  of  silicon  can  handle 
the  gate  densities  required  for  the  operation  of  a  processor 
with  the  Grigonis  specifications. 

Those  10,000-  to  15,000-megabyte  optical  disk  drives 
(10  inches  in  diameter)  also  give  me  pause.  A  conventional 
read-only  videodisk  can  easily  yield  about  2,250  megabytes  of 
storage  (333,333  bits  x  54,000  tracks),  so  Grigonis  is  talking 
about  a  five-  to  seven-fold  density  increase,  with  the  ability  to 
write  to  the  disk.  While  I  wouldn’t  say  that’s  impossible,  given 
the  unknown  technological  developments  that  will  occur  over 
the  next  ten  years,  I  think  about  3,500  megabytes  on  a  14-inch 
disk  sounds  more  realistic,  at  least  as  far  as  small  systems  are 
concerned. 

Grigonis  also  mentions  artificial  intelligence  programs  that 
could  require  32  megabytes  of  memory  with  a  virtual  memory 
system.  Since  the  internal  memory  working  set  size  of  any 
virtual  memory  system  is  usually  half  the  size  of  the  program, 
he  evidently  envisions  AI  programs  of  60  or  70  megabytes  in 
length.  These  would  be  several  times  the  size  of  the  standard 
business  applications  packages  that  his  AI  program  would 
presumably  replace. 

The  problem  of  software  quality  assurance  also  rears  its 
ugly  head.  In  an  actor-based,  artificial- intelligence  driven, 
customized  language  generator  as  described  by  Grigonis,  how 
does  one  deal  with  program  validation  if  the  language  has 
never  before  existed  and  the  programmer  is  unfamiliar  with  it, 
yet  is  fully  understood  by  the  “machine”  (meaning  the  actor- 
based  AI  program)  that  developed  it?  Can  we  be  sure  that  the 
AI  program  really  “understands”  its  own  creation?  Normally, 
locating  errors  in  code  that  is  written  in  a  well-known  lan¬ 
guage  such  as  COBOL  can  take  up  to  half  of  one’s  time  —  what 
about  the  unenviable  position  of  having  to  locate  errors  in  a 
program  written  in  a  language  totally  foreign  to  everyone? 

Besides,  it  is  my  strong  feeling  that  even  with  artificial 
intelligence,  64-bit  microprocessors,  and  many  megabytes  of 
memory,  the  supermicros  of  1992  will  all  serve  merely  as  intel¬ 
ligent  terminals  to  even  more  powerful  mainframes,  especially 
in  the  videotex  environment. 

Still,  after  years  of  looking  at  DDJ’s  countless  pages  of 
software  listings  in  weird  languages,  it  was  stimulating  to  read 
“Fifth  Generation  Computers,”  and  I  would  be  curious  to  see 
Grigonis’  speculations  on  the  workstation  environments  that 
will  have  to  be  developed  to  contain  the  operator  as  well  as 
the  advanced  hardware  he  describes. 


»»J 


by  Michael  J.  Doherty 


Michael  J.  Doherty,  334  South  Maple  Avenue,  Glen  Rock, 
New  Jersey  07452. 
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CP/M  EXCHANGE 


by  Gene  Head 


Last  month  this  column  carried  the 
source  listing  for  a  sorted  and  sized  direc¬ 
tory  listing  program,  DIR. ASM.  One  of 
the  more  obscure  sections  of  that  code 
dealt  with  the  Disk  Parameter  Block  and 
the  computation  of  space  available  on  a 
partially  filled  disk. 

Frankly,  I  don’t  understand  as  much 
as  I  would  like  to  about  disk  tracks,  sec¬ 
tors,  records  and  the  like.  Bob  Blum  has 
contributed  two  articles  that  he  says  will 
clear  up  some  of  the  foggy  parts  about 
basic  disk  I/O.  I’m  very  encouraged  by 
Bob’s  contribution  to  this  month’s  and 
next  month’s  column  for  three  reasons. 

First,  Bob  is  a  perfect  example  of 
readers  sharing  their  experience  with  the 
rest  of  us;  Dr.  Dobb’s  specializes  in  this. 
Second,  Bob  wrote  the  article  and  sent  it 
to  me  via  modem;  our  computers  are 
helping  us  communicate  effectively!  Fi¬ 
nally,  I  hope  other  readers  will  see  how 
helpful  their  input  is  and  send  in  their 
ideas. 

Perhaps  the  mysteries  surrounding 
the  CBIOS  to  BDOS  interface  have  dis¬ 
couraged  you  from  upgrading  to  a  higher 
performance  disk  system  or  from  making 
a  few  of  those  changes  that  could  make 
your  system  more  livable.  In  this,  the  first 
of  a  two-part  series,  we  will  review  the 
major  aspects  of  the  most  popular  disk 
drives  in  use  today  and  the  data  alloca¬ 
tion  methods  used.  This  will  set  the  stage 
for  next  month’s  article  where  the  disk 
interface  portion  of  the  CBIOS  will  be 
covered  in  detail.  At  the  conclusion,  I 
hope  you  will  feel  more  comfortable  with 
CBIOS’s  inner  workings  and  consider  it  a 
friend  rather  than  a  foe. 

3740  Format 

Several  years  ago,  IBM  introduced 
the  3740  data  entry  system  which  used 
8”  floppy  disks  for  external  storage.  As  is 
characteristic  of  the  computer  industry  in 
general  when  IBM  introduces  a  new  prod¬ 
uct,  it  is  soon  copied  and  many  times  be¬ 
comes  a  new  standard.  This  is  the  case 
with  the  3740  disk  format.  It  was  the 
first  format  to  be  implemented  under 
CP/M  and  continues  to  be  the  standard 
today.  For  that  reason  it  will  be  used  here 
as  the  basis  for  example  until  the  discus¬ 
sion  turns  to  the  newer,  more  sophisti¬ 
cated  disk  drives. 

The  3740  configuration  is  imple¬ 
mented  using  a  single-sided,  single-density, 
soft-sectored  disk  drive.  Single-sided 
means  that  only  one  side  of  the  media  is 
used  for  recording  by  a  single  read/write 


(R/W)  head.  Referring  to  Figure  1 
(below),  each  track  of  recording  area  is 
divided  into  data  areas  called  sectors.  Sep¬ 
aration  of  consecutive  sectors  is  accom¬ 
plished  through  control  information  re¬ 
corded  along  with  the  data  portion  of  the 
sector.  This  type  of  sectoring  is  referred 
to  as  soft-sectored  format.  To  reach  any 
one  of  the  sectors,  all  we  need  to  know  is 
the  track  and  sector  numbers.  From  there 
the  disk  controller  and  CBIOS  logic  direct 
the  disk  drive  to  step  to  the  appropriate 
track  and  await  the  arrival  of  the  desired 
sector.  Sector  skewing  is  employed  to  in¬ 
crease  the  speed  at  which  sectors  can  be 
sequentially  accessed.  This  technique  off¬ 
sets  consecutive  sectors  from  each  other 
by  a  count  of  6.  Figure  4  (page  81)  lists 
the  standard  skew  table  used  in  the  3740 
standard.  The  skew  table  is  used  to  map 
logical  sectors  to  their  physical  location 
on  disk.  For  example,  your  program 
wants  to  read  logical  sector  2.  The  BDOS 
first  calls  a  translation  routine  which  uses 
the  logical  sector  number  2  as  an  index 
into  the  skew  table.  In  position  2  is  7, 
offset  from  1  by  6,  which  is  used  for  the 
actual  read  operation.  The  rate  at  which 
consecutive  sectors  can  be  sequentially 
accessed  is  greatly  improved  by  skewing 
because  most  of  the  time  it  is  possible  to 
process  the  data  just  accessed  and  prepare 
for  the  next  operation  before  the  next  se¬ 
quential  sector  passes  under  the  R/W 


head.  This  makes  it  possible  to  access  up 
to  two  sectors  per  disk  revolution.  With¬ 
out  sector  skewing,  the  best  possible  data 
rate  would  be  one  sector  per  revolution 
of  the  disk. 

CP/M  3740 

In  CP/M  3740  single -density  format 
there  are  26  128 -byte  sectors  per  track 
and  a  total  of  77  tracks  per  disk.  Sectors 
are  numbered  from  1  to  26  and  tracks 
from  0  to  76.  The  first  two  tracks  are  re¬ 
served  for  system  use.  The  boot  loader 
occupies  track  0  sector  1  while  the  re¬ 
maining  sectors  on  track  0  and  1  are  used 
to  hold  the  operating  system.  All  remain¬ 
ing  tracks  are  available  for  directory  and 
data  area  usage. 

One  of  CP/ M’s  major  advantages  is 
the  ability  to  dynamically  allocate  disk 
space  during  program  execution.  To 
accomplish  this,  allocation  groups  are 
used.  Each  group  contains  eight  consecu¬ 
tive  sectors  or  1024  bytes  and  is  the  basic 
unit  of  disk  space  which  can  be  allocated 
at  any  one  time.  Control  of  the  allocation 
and  deallocation  of  groups  during  execu¬ 
tion  of  a  program  requires  that  the  cur¬ 
rent  status  of  each  group  be  available  at 
all  times.  Memory-resident  tables  are  used 
for  this  purpose.  You  have  probably  no¬ 
ticed  that  when  logging  in  a  new  drive  or 
warm  starting,  quite  some  time  is  spent  in 
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disk  activity.  During  this  time  CP/M  is 
reading  the  entire  disk  directory  and  con¬ 
structing  a  bit  map  in  RAM.  The  bit  map 
is  appropriately  named  because  each  bit 
in  the  map  represents  the  status,  in-use 
or  available,  of  one  allocation  group.  The 
purpose  of  allocation  groups  is  to  reduce 
the  memory  requirements  of  the  bit  map 
and  to  prevent  excessive  file  fragmenta¬ 
tion.  For  example,  if  each  allocation 
group  were  one  sector  in  length,  the  bit 
map  would  contain  1944  bits  or  slightly 
over  243  bytes.  Since  the  maximum  ca¬ 
pacity  of  the  3740  system  is  243  alloca¬ 
tion  groups,  only  3  1  bytes  are  needed  to 
contain  the  bit  map  for  each  active  drive. 
This  is  a  large  memory  saving,  not  to  men¬ 
tion  the  reduction  in  head  movement  ne¬ 
cessary  to  process  1024  bytes  of  data.  To 
find  an  allocation  group  in  which  to  write, 
CP/M  searches  the  bit  map  sequentially 
from  the  beginning  until  a  zero  bit  is 
found  which  indicates  availability.  During 
the  search,  each  bit  that  is  passed  over  is 
counted.  The  resulting  count  is  used  to 
identify  the  allocation  group  and  is  used 
in  subsequent  operations  to  determine 
the  track  and  sector  numbers.  When  re¬ 
turning  allocation  groups  to  the  system, 
the  directory  entries  of  the  appropriate 
file  are  read  and  the  allocation  group 
numbers  are  extracted  from  the  FCB  and 
are  used  as  an  index  into  the  bit  map  to 
appropriately  adjust  it. 

Double-Sided  Drives 

As  microcomputers  found  more  com¬ 
mon  use  in  commercial  data  processing, 
more  capacity  on  the  same  size  media 
created  the  need  and  subsequent  intro¬ 
duction  of  the  double-sided  drive.  In  this 
configuration  there  is  one  stationary  and 
one  movable  R/W  head  as  in  the  single¬ 
sided  drive.  This  type  of  drive  still  gives 
engineers  fits  because  of  unacceptable 
wear  patterns,  media  warping  when  both 
heads  were  engaged  and  gravity  problems 
since  the  lower  head  must  be  held  in 
place  against  gravity.  This  also  presented 
some  new  problems  for  the  driver  soft¬ 
ware  and  the  disk  controller  because  it 
was  now  necessary  to  command  the  drive 
to  read  or  write  from  a  particular  head  in 
addition  to  track  and  sector.  One  method 
of  adapting  to  this  new  drive  was  to  map 
one  logical  single-sided  disk  to  each  side 
of  the  two-sided  disk.  This  achieves  the 
desired  result  of  twice  the  storage  capac¬ 
ity  but  has  one  inherent  disadvantage  — 
excessive  head  movement  which  slows 
data  transfer,  sometimes  to  an  unaccepta¬ 
ble  limit.  The  common  solution  was  to 
logically  view  the  drive  as  having  twice  as 
many  tracks  as  it  really  had.  Referring  to 
Figure  2,  it  is  common  on  a  40-track, 
double -sided  drive  to  assign  all  tracks  on 
size  zero  even  numbers  between  0  and  78 
while  side  one’s  tracks  are  assigned  odd 
numbers  between  1  and  79.  Since  the  disk 
controller  will  only  recognize  tracks  0 
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through  39,  the  CBIOS  has  to  translate 
logical  tracks  to  physical  tracks  and  set 
the  appropriate  head  selection  line.  This 
calculation  is  not  too  difficult.  Referring 
to  Figure  3,  divide  the  logical  track  num¬ 
ber  by  two.  The  quotient  is  the  physical 
track  number  and  the  remainder  is  used 
to  select  the  appropriate  head.  From  this 
we  can  see  that  both  tracks  0  and  1  are 
under  the  R/W  heads  at  the  same  time 
and  can  be  visualized  as  a  cylinder.  This 
technique  provides  faster  data  transfer 
because  no  mechanical  movement  is  ne¬ 
cessary  to  process  two  complete  tracks  of 
data. 

Certain  manufacturers  weren’t  satis¬ 
fied  with  only  double  the  capacity,  so 
double-density  recording  methods  were 
developed  which  provided  approximately 
twice  as  much  data  content  in  each  of  the 
sectors  and  twice  the  transfer  rate.  Today, 
even  more  data  is  being  packed  onto  each 
disk  by  increasing  the  number  of  tracks 
and  using  group  encoding.  It’s  fairly  com¬ 
mon  to  find  640K  bytes  of  data  being 
stored  onto  one  514”  floppy  disk.  With 
motor  speed  control,  it  is  possible  to 
store  512K  bytes  on  a  single-sided  disk 
system  as  on  the  Victor  9000.  The  reward 
for  greatest  capacity  on  a  5lA"  floppy  is 
held  by  a  British  firm,  Rair,  which  offers 
over  800K  on  one  disk  by  double-sided, 
quad-density  formatting. 

Along  came  hard  disks  and  still  fur¬ 
ther  increased  storage  capacity.  It  is  not 
uncommon  to  have  200  tracks  and  six  or 
eight  recording  surfaces  provided  by  three 
or  four  platters  on  hard  disks.  Data  trans¬ 
fer  rates  are  also  considerably  faster  be¬ 
cause  rotation  speeds  of  approximately 
3000  to  3600  RPM  are  common.  With 
each  movement  of  the  R/W  heads,  more 
data  are  available  because  the  cylinder  has 
grown  to  multiple  surfaces. 

There  is  much  more  to  cover  in  this 
track  and  sector  discussion.  If  you  have 
further  questions,  send  me  a  SASE  and  I 
will  return  to  you  a  list  of  reference  ma¬ 
terials  which  will  explain  these  subjects  in 
greater  detail.  Next  month  we  will  get 
straight  to  the  heart  of  the  interface  ta¬ 
bles  and  their  relationship  to  the  system. 


(Figures  2,  3,  and  4  on  next  page.) 
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FIGURE  3. 


1,  7,  13,  19,  25,  5,  11,  17,  23,  3,  9,  15,  21,  2, 

8,  14,  20,  26,  6,  12,  18,  24,  4,  10,  16,  22 

FIGURE  4. 

Format 

Code 

1. 

8”  Single-Sided/ Single -Density 

8SS/SD 

2. 

8”  Double-Sided/Single-Density 

8DS/SD 

3. 

8”  Single-Sided/ Double- Density 

8SS/DD 

4. 

8”  Double-Sided/Double-Density 

8DS/DD 

5. 

514”  Single-Sided/Single-Density 

5SS/SD 

6. 

514”  Single-Sided/Double-Density 

5SS/DD 

7. 

514”  Double-Sided/Single-Density 

5DS/SD 

8. 

514”  Double-Sided/ Double-Density 

5DS/DD 

9. 

514”  Double-Sided/ Quad-Density 

5  DS/QD 

10. 

514”  Single-Sided/Double-Density/Variable  Speed 

5  SS/DD/V 

11. 

514”  Double-Sided/ Double-Density/ Variable  Speed 

Table  1. 

5  DS/DD/V 
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DR.  DOBB’S  CLINIC 

by  D.  E.  Cortesi 


The  Eternal  Calendar 

Calendar  algorithms  are  an  unfailing 
source  of  fun  and  agony  for  programmers. 
Early  in  this  column’s  history,  we  proposed 
some  calendar  code.  We  also  worked  on 
some  problems  in  BASIC  coding  whose 
solutions  revolved  around  using  the  arith¬ 
metic  value  of  relational  expressions. 
Brian  Moore  of  Oakland,  CA,  was  going 
through  his  back  issues  of  DDJ and  was  in¬ 
spired  by  those  old  problems  to  propose  a 
calendar  algorithm  for  BASIC  which  uses 
the  arithmetic  value  of  relations. 

Moore’s  algorithm  takes  a  day-of- 
the-year  number  as  its  input,  and  a  boolean 
value  that  is  “true”  if  this  is  a  leap  year. 
In  one  big  expression,  it  biases  or  offsets 
the  day  number  to  the  value  it  would 
have  if  all  months  were  31  days  long.  The 
month  number  and  the  day-of-the-month 
number  are  obtained  from  that  value  by 
dividing  by  31.  Our  version  of  Moore’s 
code  (Listing  1,  below)  is  for  the  more 
common  BASICS,  in  which  “true”  is  rep¬ 
resented  as  negative  one  and  “false”  as 
zero.  Some  BASICS  represent  “true”  as 
positive  one;  if  that  is  true  of  yours, 
change  all  minus  signs  in  line  1040  to 
plus,  and  vice  versa. 

The  Productive  Erase 

Aubrey  Hutchison,  of  Pompano 
Beach,  FL,  sends  us  an  idea  that  is  (we 
think)  eccentrically  brilliant.  First,  some 
background.  CP/M  2.2  supports  the  no¬ 
tion  of  a  user  number,  a  number  in  0..15 
that  is  an  implicit  part  of  all  filenames  on 
a  disk.  There  is  a  current  user  number 
(set  with  the  USER  command)  which 
qualifies  all  searches  of  the  directory,  so 
that  the  only  files  you  can  see  are  those 


that  were  created  under  the  current  user 
number.  It’s  a  nice  idea  —  it  allows  the 
directory  of  a  large  disk  to  be  partitioned 
into  as  many  as  16  sub -directories  —  but 
it  wasn’t  carried  out  thoroughly  enough. 
Later  versions  of  CP/M  (CP/M  3,  Concur¬ 
rent  CP/M,  MP/M  2,  and  MP/M  86)  make 
the  user  number  more  useful. 

One  problem  with  the  user  number 
(as  implemented  in  CP/M  2.2)  is  that 
there  is  no  simple  way  to  move  files  from 
one  user  number  to  another.  You  can  do 
it  with  PIP;  its  [G]  option  will  cause  it  to 
search  for  the  source  file(s)  under  a  dif¬ 
ferent  user  number  than  the  current  one. 
But  since  the  only  commands  you  can  use 
are  those  stored  under  the  current  number, 
you  have  to  have  a  copy  of  PIP  under 
every  user  number  you’ll  use.  And  if  you 
want  a  file  to  appear  under  two  user  num¬ 
bers,  you  have  to  have  two  copies  of  it, 
one  stored  under  each  number. 

Well,  Hutchison  was  pondering  these 
matters,  and  thinking  about  the  fact  that 
the  user  number  is  stored  in  the  first  byte 
of  directory  entry  as  a  value  from  OOh  to 
OFh,  when  he  had  a  satori  of  sorts.  He 
flashed  on  the  fact  that,  when  the  BDOS 
erases  a  file,  it  simply  stores  E5h  in  the 
first  byte  of  the  file’s  directory  entry.  So 
changing  the  user  number  of  a  file  and 
erasing  it  are  identical  operations,  namely, 
storing  something  in  the  first  byte  of  the 
directory  entry.  In  order  to  change  the 
user  code  of  a  file,  all  that  is  needed  is  to 
persuade  the  BDOS  to  use  the  user  num¬ 
ber  instead  of  E5h  for  erasure,  and  then 
to  erase  the  file. 

Hutchison  went  looking  for  the 
magic  constant  of  E5h  in  the  BDOS,  and 
he  found  it.  Just  655h  bytes  below  the 
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warm-start  entry  point  of  your  BIOS 
(whose  address  is  in  location  000  lh) 
there  is  an  instruction,  “MVI  M,E5h.” 
If  that  is  changed  to,  say,  “MVI  M,03h” 
and  the  BDOS  is  called  to  erase  a  file,  the 
file  won’t  be  erased.  It’ll  be  given  user 
number  3  instead.  Of  course,  the  BDOS  is 
refreshed  from  disk  whenever  a  warm  start 
is  done,  so  the  zap  has  to  be  made  on  the 
fly.  You  can’t  expect  to  do  it  with  DDT, 
because  the  BDOS  will  be  refreshed  when 
the  DDT  ends. 

But  you  could  write  a  GO-USF.R 
command  that  takes  a  user  number  and  a 
file-spec,  patches  the  BDOS  on  the  fly, 
erases  the  filespec,  and  ends.  Before  the 
command  ends,  it  should  un-patch  the 
BDOS.  That’s  because  there  are  a  few 
times  when  the  BDOS  is  not  reloaded 
from  disk  on  a  warm  start  —  like  when¬ 
ever  XSUB  is  running. 

A  Pascal  Standard  At  Last! 

Members  of  the  IEEE  Computer 
Society  got  gladsome  news  in  the  mail 
just  before  Christmas,  in  the  form  of  an 
ad  for  the  book  American  National  Stan¬ 
dard  Pascal.  According  to  the  ad,  “IEEE 
Standard  Pascal  has  completed  its  IEEE 
approval  and  is  undergoing  final  ANSI 
approval  at  this  time  .  .  .  (it)  provides  an 
unambiguous  and  machine  independent 
definition  of  the  language.”  The  cloth- 
bound  book  is  the  official  standards  doc¬ 
ument;  it  costs  $17.95  to  non-members, 
$16.95  to  members  of  the  Computer 
Society,  and  should  be  shipped  in  Janu¬ 
ary.  Order  from  IEEE  Computer  Society, 
10662  Los  Vaqueros  Circle,  Los  Alamitos, 
CA  90720. 

We  know  at  least  one  software  outfit 
that  has  made  frequent  public  promises 
to  bring  its  compiler  into  conformance 
with  the  standard  language  “just  as  soon 
as  there  is  an  approved,  not  a  draft,  stan¬ 
dard.”  Don’t  hold  your  breath;  they’ll 
probably  claim  they  really  meant  an  inter¬ 
national  standard,  not  just  an  American 
one. 

Dempsey’s  Dilemma 

J.  Dempsey,  of  Seattle,  WA,  has  a 
sticky  problem,  one  that  most  computer 
makers  would  prefer  not  to  think  about. 
Dempsey  says,  “I  do  writing  in  a  techni¬ 
cal  field  (linguistics)  where  I  need  to  use 
a  variety  of  special  symbols.  As  far  as 
possible,  these  should  have  equal  status 
with  the  regular  alphanumerics.  I’ve  seen 
articles  on  how  to  generate  such  symbols 


Listing  1. 

1000  REM  GIVEN:  DAY  IN  1 . . 366 ,  A  DAY  0E  THE  YEAR,  AND 
1010  REM  LEAP  =  TRUE  (-1)  OR  FALSE  (0), 

1020  REM  RETURN  MONTH  IN  1..12,  DATE  IN  1  -  -  31 
1040  DI  =  DAY  -  1 

-  (DAY  >  (59-LEAP))  *  (3+LEAP) 

-  (DAY  >  (120-LEAP)) 

-  (DAY  >  ( 181-LEAP) ) 

-  (DAY  >  (273-LEAP)) 

-  (DAY  >  (334-LEAP)) 

1050  MONTH  =  INT(DI/31)+1 
1060  DATE  =  (DI  MOD  31)+1 
1070  RETURN 

1080  REM  GIVEN  YEAR  IN  0..9999,  RETURN  LEAP  TRUE  OR  FALSE 
1090  LEAP  =  ((YEAR  MOD  4)=0)  *  ((YEAR  MOD  400)00) 

1100  RETURN 
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on  an  IBM  PC,  Apple,  etc.  but  always  in 
a  graphics,  not  a  text,  mode.  [I  assume 
that  such  characters]  are  therefore  in 
poorer  resolution  than  ordinary  ones, 
clumsy  to  use  from  the  keyboard,  and 
presumably  useless  for  word-processing 
or  data  bases.  What  do  I  do?” 

What,  indeed?  Before  you  rush  to 
answer,  take  a  close  look  at  one  of  the 
examples  Dempsey  sent  along  (see  box, 
this  page).  It’s  all  very  well  to  note  that 
the  Atari,  the  PC,  the  Victor  9000,  etc., 
all  have  screen  character  sets  that  can  be 
partly  or  completely  redesigned  by  the 
user;  getting  the  symbols  onto  the  screen 
is  only  a  tenth  of  the  battle. 

Let’s  call  symbols  like  the  ones 
Dempsey  works  with  specialist  symbols: 
symbols  not  in  the  standard  ASCII  set, 
but  which  are  commonplace  in  some  spe¬ 
cialist’s  field  —  linguistics  in  this  case. 
Law,  medicine,  mathematics,  indeed 
every  profession,  makes  use  of  its  own  set 
of  specialist  symbols.  The  International 
Phonetic  Alphabet  is  one  set  of  specialist 
symbols  that  it  would  be  nice  to  have 
when  working  with,  or  writing  about,  the 
Votrax  speech  synthesizer.  Choreogra¬ 
phers  have  an  “alphabet”  of  dance  move¬ 
ments;  at  one  time  IBM  offered  a  Selectric 
typeball  for  it.  Someone  editing  a  diction¬ 
ary  would  like  to  have  a  set  of  diacritical 
marks.  And  so  on. 

With  many  personal  computers,  we 
can  put  a  set  of  specialist  symbols  on  the 
screen,  but  only  by  replacing  some  part 
of  the  machine’s  native  font.  The  specialist 
characters  are  folded  into  the  “letter 
space”  of  0..255,  and  so  are  ambiguous 
when  stored  in  RAM  or  a  file.  A  file  con¬ 
taining  them  might  look  right  when  dis¬ 


played  on  the  screen  (provided  the  right 
user-defined  text  font  is  loaded),  but  will 
those  byte  values  be  processed  correctly 
by  a  sort?  And  how  can  they  be  printed? 
A  fundamental  problem  is  that  the  8 -bit 
symbol  space  is  too  small  to  accommodate 
more  than  one  alphabet.  This  doesn’t 
hurt  when  the  problem  is  to  accommodate 
a  foreign  language  (although  there  is  a 
problem  when  the  foreign  alphabet  has  a 
large  number  of  symbols,  as  with  some 
oriental  languages).  But  specialist  symbols 
are  an  extension  of  the  standard  alphabet, 
not  a  replacement  for  it. 

There’s  a  mechanical  problem,  too; 
how  do  you  arrange  a  keyboard  to  allow 
for  a  large  vocabulary  of  specialist  char¬ 
acters?  The  usual  answer  is,  as  before, 
folding  —  some  keys  are  preempted  to 
stand  for  special  codes.  One  of  the  IBM 
PC’s  best  features  is  its  ALT-shifted  key 
values.  When  we  first  saw  it,  we  thought 
it  was  useless,  but  the  longer  we  work 
with  it,  the  more  uses  we  find  for  that 
third  shift-mode. 

At  any  rate,  has  any  reader  got  either 
practical  hints  for  Dempsey  on  what  sys¬ 
tem  and  software  to  look  at,  or  more 
general  comments  on  the  whole  problem 
of  specialist  symbols? 

Backward  with  the  PC  .  .  . 

The  IBM  PC  does  something  very 
odd  if  you  write  a  Backspace  code  (08h) 
from  BASIC.  If  you  write  a  Backspace 
when  the  cursor  is  at  the  left  margin, 
nothing  happens  (which  is  just  as  it 
should  be).  But  if  you  write  a  Backspace 
when  the  cursor  is  away  from  the  margin, 
you  get,  not  a  leftward  movement  of  the 
cursor,  but  a  funny  little  graphics  symbol, 


a  small  reverse-video  diamond.  Try  this 
to  see  it : 

PRINT  “>”+CHR$(8) 

Beyond  the  irritation  of  not  having  a 
Backspace  that  backspaces,  we  find  this 
puzzling  because  we  pored  over  the  BIOS 
listing  in  the  Technical  Reference  manual 
and  we  can’t  see  where  the  bug  is.  Maybe 
it’s  in  BASIC.  Furthermore,  the  symbol 
displayed  is  not  any  of  the  ones  docu¬ 
mented  in  any  PC  manual  that  we  can 
find,  nor  is  it  a  reverse-video  version  of 
one  of  them.  Can  anyone  explain  these 
things? 

. .  .  Also  Up,  Down,  and  Around  . . . 

If  you  are  using  CP/M-86  on  a  PC, 
you  will  find  that  the  BDOS  has  a  rudi¬ 
mentary  form  of  terminal  emulation  built 
into  it,  so  that  the  PC’s  display  can  be 
programmed  as  if  it  were  a  terminal  with 
an  addressable  cursor.  The  BDOS  (not  the 
PC’s  firmware)  supports  escape  sequences 
to  set  the  cursor  location  and  to  access 
various  other  features. 

If  you  are  using  MSDOS,  you  don’t 
have  this  option.  Cursor  addressing  be¬ 
comes  a  matter  of  some  rather  advanced 
PEEKS  and  POKES,  or  their  equivalent 
in  whatever  language  you  are  using.  One 
thing  that  might  help  is  to  note  that  the 
ASCII  control  characters  FS,  GS,  RS,  and 
US  (ICh,  lDh,  1  Eh,  and  lFh)  are  defined 
by  BASIC  as  moving  the  cursor  right,  left, 
up,  and  down,  respectively.  However,  this 
appears  to  be  a  BASIC  function,  not 
something  built  into  the  ROM  BIOS  or 
the  CRT  controller  chip.  From  assembly 
language,  you  can  call  the  ROM  BIOS 
directly;  what  you  do  from  Pascal  or 
COBOL,  we  don’t  know.  Do  you? 

.  .  .  And  BASICally  Slower. 

Bob  Pirko,  of  New  York,  took  us  up 
on  our  recent  challenge;  he  has  explored 
the  contents  of  IBM  BASIC  and  demon¬ 
strated  to  his  own  satisfaction  and  ours 
that  it  is  definitely  a  mechanical  transla¬ 
tion  from  8080  code.  He  writes  as 
follows: 

“I  own  an  IBM  PC,  and  like  you,  I 
found  IBM  BASIC  to  be  slower  than  1 
had  expected.  Having  traced  the  execu¬ 
tion  of  a  few  statements  in  BASIC,  I  can 
offer  some  reasons  for  lack  of  speed. 

“Much  of  the  code  is  undoubtedly  a 
mechanical  translation  of  8080  code. 
Attached  are  three  samples  (see  Listing  2, 
page  85)  which  list  the  code  from  the  IBM 
PC’s  ROM,  the  equivalent  8080  code,  and 
more  efficient  8088  code.  Table  1  (page 
84)  gives  execution  times  for  each  of 
these  routines. 

“The  IBM  ROM  routines  are  two  to 
six  times  slower  than  they  could  be,  and 
approximately  twice  as  slow  as  compara¬ 
ble  8080  code.  While  such  cases  demon¬ 
strate  the  perils  of  mechanical  translation, 
most  of  the  code  in  IBM  BASIC  is  not 


An  example  of  “specialist  symbols.” 

jafy  na/ar  deha:ti  bema  fa:hr  dar  barzarr  a/b 

A  peasant  came  to  the  city;  He  was  going  along  in  the  bazaar. 

berasa:  be  dokku.-ne  yanna.-li  fi:ri:ni:ha:je  rajij  rajij 

He  reached  the  shop  of  a  confectioner.  Confectionery  of  different  kinds 

dokkun  dar/un  tfi:  bu  i:n  Ji:ri:nforu:f  a:he  vc 

was  set  out  in  the  shop.  This  confectioner  was  sitting  and 

ajijnft  merde  deharti:  xijaiUJ  ka  yannard  ku:rt 

looking.  The  peasant  thought  that  the  confectioner  was  blind. 

dr,aldi  befo  merde  dehiuti:  do  ta:  urjgu-.jl  dyle 

He  went  (forward)  quickly.  The  peasant  held  his  two  fingers  before 

tfamjef  da:  yannarlcj  be/va  tfera  t:n 

his  (the  confectioner’s)  eyes.  The  confectioner  said  to  him,  “  Why  did 

ka:rel  be\e  merde  deharti  be/va  man  xijadem  ke  to  ku:ri: 

you  do  this  ?  ”  The  peasant  said,  “  I  thought  you  were  blind.” 

man  ku:r  neha:  a vtrnon  deha:ti  be/va  ajar  to  am:ni  l/era:  to 
“I  am  not  blind;  I  see.”  The  peasant  said,  “If  you  see  why 

/i:ri:nija:  naxcri. 

do  you  not  eat  the  confectionery  1  ” 
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Table  1. 

1 

Sample  Execut 

ion  Times 

In 

M i cro-Seconds 

1 

i 

1 

1 

1  IBM  ROM 

1 

* 

Equivalent  1 
8080  **  1 

Ef f icient 
8088  * 

1 

1 

1 

1 

1. 

Add  AL  to  BX 

1  8. 9 

4. 0  1 

2.  6 

1 

1 

1 

2. 

Immediate  minus  BX 

1  10. 5 

6. 0  1 

5.  3 

1 

1 

1 

3. 

String  Move (20  bytes) 

1  409.  6 

188.0  1 

72.  9 

I 

1 

*  Based  on  time  test  run  on  an 
**  Calculated  for  5  Mhz.  8085. 

IBM 

PC. 

1 

quite  so  bad.  In  fact,  some  of  it  has  been 
optimized  to  use  the  superior  features  of 
the  8088’s  instruction  set.  Still,  most 
routines  take  longer  than  similar  8080 
code  executing  on  a  5MHZ  8085  or  even 
a  4MHZ  Z80. 

“Generally,  the  8088  will  execute 
fewer  instructions  per  second  than  an 
8085  or  a  Z80.  This  may  seem  surprising, 
but  shouldn’t  be.  The  rate  at  which  in¬ 
structions  are  executed  is  only  one  of  the 
factors  which  determine  speed.  Of  equal 
importance  is  the  quantity  of  useful  work 
done  by  each  instruction.  Happily,  the 
8088  repertoire  contains  a  large  number 
of  operations  which  do  as  much  work  as 


two  or  more  8080  instructions.  It  is  only 
by  effective  use  of  these  instructions  that 
an  8088  can  reach  its  true  potential. 
Translated  code  is  slow  because  it  consists 
of  just  those  8088  instructions  that  are 
functionally  equivalent  to  8080  instruc¬ 
tions. 

“The  8080  has  many  one-byte  in¬ 
structions  that  execute  in  one  memory 
access  cycle.  The  equivalent  8088  code 
requires  two  bytes  and  often  takes  two 
memory  cycles  (eight  clock  cycles)  to 
execute.  Intel  manuals  list  shorter  times, 
but  they  assume  that  the  instruction  has 
been  pre-fetched  and  is  waiting  in  the 
internal  queue  when  needed.  This  is  often 


untrue,  especially  for  the  kind  of  code 
produced  by  a  translator  program. 

“In  summary,  even  if  Microsoft  had 
done_a_helter  job  at  optimizing  the  trans¬ 
lated  code,  the  performance  would  still 
have  been  below  expectations.  Really 
efficient  code  would  have  required  a 
complete  rewrite  of  BASIC.  This  would 
be  an  ideal  project  for  someone  with  a 
couple  of  years  available  and  nothing 
better  to  do.” 
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Listing  2. 


IBM 

Example  1  — 

Add  8  bit  value  in 

AL  to 

BX 

ROM  Code 

Equivalent 

8080 

code 

Efficient  8088  code 

ROM  Address 

ROM 

Code 

F600: 1893 

ADD 

AL,  BL 

ADD 

L 

CBW 

F600: 1895 

MOV 

BL,  AL 

MOV 

L,  A 

ADD  BX , AX 

F600: 1897 

ADC 

AL,  BH 

ADC 

H 

F600: 1899 

SUB 

AL,  BL 

SUB 

L 

F600: 189B 

MOV 

BH,  AL 

MOV 

H,  A 

This  code  is  executed  whenever  one  of  the  four  arithmetic  operators  is  specified.  It  is  used  to  compute  the  address  of  the  appro¬ 
priate  arithmetic  routine.  The  value  in  AL  is  always  less  than  7FH  so  CBW  gives  the  correct  result.  The  efficient  code  does  not 
preserve  the  contents  of  AH  as  does  the  ROM  code.  This  is  no  problem  because  the  subsequent  code  does  not  expect  any  value  to 
be  passed  in  AH.  Indeed,  it  would  be  surprising  if  it  did  since  translated  code  doesn’t  know  that  the  AH  register  even  exists. 


Example  £  —  Subtract  BX  from  an  immediate  value  <0FF£6H) 


IBM  ROM  Code 


Equivalent  8080  code  Efficient  8088  code 


ROM  Address  ROM  Code 


F600 : £CE0 

MOV 

AL 

F600 : £CE£ 

SUB 

AL 

F600 : £CE4 

MOV 

BL 

F600 : £CE6 

MOV 

AL 

F600:£CE8 

SBB 

AL 

F600 : £CEA 

MOV 

BH 

£6H 

MV  I 

A,  £6H 

BL 

SUB 

L 

AL 

MOV 

L,  A 

0FFH 

MV  I 

A, 0FFH 

BH 

SBB 

H 

AL 

MOV 

H,  A 

NEG  BX 

SUB  BX, 0DAH 


This  is  executed  once  for  each  variable  in  a  BASIC  statement.  I  think  this  routine  checks  whether  the  stack  has  overrun  its  limits. 
I  used  SUB  BX.ODAH  rather  than  the  more  natural  ADD  BX,0FF26H  in  order  to  set  the  flags  the  same  as  the  original  code. 


Example  3  —  String  move 


IBM 

ROM  Code 

Equivalent  8080 

code 

Efficient 

8088  i 

30M  Address 

ROM 

Code 

F600 : £895 

INC 

BL 

INR 

L 

F600:£897 

DEC 

BL 

MOVE IT:  DCR 

L 

MOV 

SI,  CX 

F600:£899 

JNZ 

£89CH 

MOV 

DI,  DX 

F600:£89B 

RET 

RZ 

MOV 

CL,  BL 

F600 : £89C 

MOV 

SI,  CX 

XOR 

CH,  CH 

F600 : £89E 

LODSB 

LDAX 

B 

REP  MOVSB 

F600 : £89F 

MOV 

DI,  DX 

MOV 

DX,  DI 

F600 : £8A1 

STOSB 

STAX 

D 

RET 

F600 : £8A£ 

INC 

CX 

INX 

B 

F600 : £8A3 

INC 

DX 

INX 

D 

. 

F600:£8A4 

JMP 

£897H 

JMP 

MOVE IT 

This  routine  is  used  by  BASIC  to  move  string  variables.  It  shows  how  bad  mechanical  translation  can  be.  The  8080  uses  BC  and 
DE  as  memory  pointers.  The  Intel  standard  is  to  equate  BC  and  DE  with  CX  and  DX  respectively,  and  the  ROM  obeys  this  con¬ 
vention.  Since  CX  and  DX  can’t  be  used  as  memory  pointers  the  ROM  must  add  instructions  to  move  the  addresses  to  SI  and  DI. 
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OF  INTEREST 


by  Michael  Wiesenberg 


Move  Over  Ada,  Here  Comes  Beb 

The  Department  of  Offense  has  an¬ 
nounced  Beb,  their  new  programming 
language  named  after  Mary  Shelley’s 
maid’s  daughter,  B’eb,  now  conceded 
to  have  been  the  world’s  first  comput¬ 
er  programmer.  B’eb  is  reliably  docu¬ 
mented  as  having  programmed  an  idiot 
savant  to  balance  her  checkbook  in 
1829,  three  years  before  Lord  Byron’s 
daughter,  Ada,  even  met  Charles  Bab¬ 
bage  (and,  in  fact,  several  years  before 
checkbooks  were  even  in  the  hands  of 
the  general  public).  Beb  uses  the  IF  .  .  . 
THEN  ..  .ELSE.  .  .BUT  ON  THE 
OTHER  HAND  construct.  A  RANDOM 
GOTO  statement  randomly  jumps  to 
any  program  line;  its  EXTERNAL  op¬ 
tion  causes  a  jump  to  any  random 
memory  location,  including  some  not 
accessible  to  the  processor.  Beb  saves 
program  space  by  writing  all  data  to 
code  space.  Not  only  does  Beb  have  no 
I/O  routines,  it  does  not  permit  them 
to  be  written.  Beb  incorrectly  executes 
subroutines  written  in  any  other  pro¬ 
gramming  language.  Optimizing  rou¬ 
tines  reduce  any  source  program  to 
exactly  three  bytes  of  object  code. 
Conditional  compilation  causes  the 
computer  to  compile  your  program 
only  if  it  feels  like  it.  Nested  infinite 
loops  lock  up  the  CPU,  bringing  any 
time-sharing  system  to  its  knees. 
Touted  as  the  first  truly  portable  lan¬ 
guage,  Beb  can  be  installed  on  any 
electrical  appliance,  including  such 
popular  machines  as  VersaTeller  and 
all  Toshiba  microwave  ovens.  Reader 
Service  No.  3.141  59265. 


A  Trendy  Giggle 

Here’s  a  new  word  for  you  to  prac¬ 
tice;  gigabyte.  It  means  “one  billion 
bytes.”  That  is,  a  thousand  megabytes. 
It’s  pronounced  with  a  hard  g  followed 
by  a  short I’ve  been  reporting  disk 
drives  with  ever  more  storage,  up  to 
160  megabytes  and  counting.  We  re¬ 
cently  received  notice  from  Capital 
Systems  that  they  will  be  a  distributor 
of  IBIS  Systems  IBM-plug  compatible 
1.25-  and  2.52-gigabyte  drives  for 
mainframes,  primarily  for  sale  to  U.S. 
government  agencies.  Not  for  the  per¬ 
sonal  computing  crowd  yet,  nor  were 
prices  even  quoted,  but  soon  you’ll  be 
seeing  a  lot  of  that  word.  And  remem¬ 
ber  the  abbreviation  GB.  (Or  should  it 
be  “Gb,”  to  be  consistent  with  “Mb” 


86 


for  megabyte?)  And  try  to  think  what 
you  could  do  with  all  that  storage .  .  .  . 
IBIS  also  makes  a  disk  drive  controller 
for  drives  with  storage  capacities  up  to 
40  Gb\  (And  don’t  ask  me  if  that’s 
really  a  billion,  or  1024-cubed.  .  .  .) 
Reader  Service  No.  101. 


A  Wonderful 

Software  Marketing  Trend 

BLOWUP,  written  in  BASIC  for 
the  IBM  PC,  transforms  text  into  inch- 
high  (ten  characters  by  ten  lines)  block 
characters  on  a  printer  for  signs  and 
notices.  Not  only  does  the  514-inch 
diskette  retail  for  only  $24.95,  but  it 
introduces  an  unusual  but  welcome 
distribution  philosophy  to  software 
marketing  that  I  hope  becomes  a  wide¬ 
spread  trend.  Robert  A.  Murray  and 
Associates  encourage  you  to  copy  the 
software  and  give  it  to  friends,  with 
the  philosophy  that  “good,  inexpen¬ 
sive  software  will  sell  itself.”  They  ask 
only  that  those  who  find  the  software 
acceptable  send  them  $20,  in  return 
for  which  they  will  receive  a  free  cata¬ 
logue  of  other  Murray  software  prod¬ 
ucts.  The  honorsystem:  what  a  refresh¬ 
ing  answer  to  piracy!  Reader  Service 
No.  103. 


Color  It  Any  Color 

USI  has  introduced  a  14-inch 
color  monitor  with  a  high  resolution, 
80-column,  24-line  display  in  seven 
colors  that  retails  for  $399.  This  is  a 
vast  improvement  over  a  TV  set,  which 
is  not  made  to  be  a  computer  monitor, 
its  low  resolution  producing  blurry 
characters  and  fuzzy  graphics.  USI  last 
year  gave  this  country  its  first  amber 
screen  monitor.  Both  monitors,  and  a 
green  phosphor  model,  are  available  in 
9-  or  12-inch  sizes.  Each  USI  monitor 
is  housed  in  a  stackable  metal  case  and 
is  style-  and  color-coordinated  with 
most  popular  computers,  to  which 
they  connect  with  standard  phono 
jacks.  Reader  Service  No.  105. 

And  for  a  screen  dump  to  printer 
of  your  wonderful  color  displays,  the 
Transtar  315  prints  in  color  for  the 
same  price  as  many  black-and-white 
dot  matrix  printers.  For  $599  you  get 
a  four-hammer  print  head  and  the 
ability  to  print  seven  colors  plus  more 
than  30  shades  in  a  single  pass.  Color 


graphics  and  characters  both  print  at 
50  cps.  Print  speed  has  little  meaning 
in  many  printers  that  intermix  colors 
in  multiple  passes  or  multiple  strikes 
at  the  same  spot,  but  the  Transtar  3  15 
does  not  slow  down,  pause,  or  come 
back.  And  thus  throughput  “exceeds 
machines  rated  at  200  cps.”  You  can 
get  an  interface  option  right  now  for 
Apple)  [  (and  for  other  computers 
soon)  called  PICS  that  lets  you  press 
a  copy  button  on  the  printer  to  get  a 
direct  color  graphics  dump  of  the 
screen  without  using  disks,  exiting  pro¬ 
grams,  or  changing  application  pro¬ 
grams.  Transtar  also  offers  a  daisy 
wheel  printer,  the  Transtar  130,  for 
$895,  that  immediately  runs  from 
most  micros  with  all  word  processing 
packages  that  have  Diablo  print  rou¬ 
tines.  You  get  boldface,  underscore, 
proportional  and  incremental  spacing, 
parallel  or  serial  interface  (one  or  the 
other),  300  to  2400  baud,  16  cps 
throughput,  auto  paper  loading,  bi¬ 
directional  printing,  and  a  six -month 
warranty.  There  is  also  a  Transtar  140, 
for  which  they  didn’t  quote  a  price, 
that  has  all  of  the  preceding,  plus  40 
cps  and  a  bidirectional  tractor  feed 
option.  (The  printers,  by  the  way,  are 
all  made  by  Seiko’s  Seikosha  Group.) 
Reader  Service  No.  107. 


Adding  to  Your  Color  Computer 

Enhance  BASIC  on  your  TRS-80 
Color  Computer  with  Spectrum  Pro¬ 
jects’  Basic  Aid,  a  ROM  cartridge  that 
sells  for  $39.95.  Automatic  line  num¬ 
bering,  single-key  entry  of  most  com¬ 
mands,  redefinition  of  keys,  merging 
routines  stored  on  tape  into  a  program 
in  memory  with  automatic  renumber¬ 
ing  so  tape  libraries  can  be  built, 
moving  of  any  program  lines  anywhere 
about  a  program  with  consequent  re¬ 
numbering  of  all  GOTOs,  GOSUBs, 
and  so  on,  that  reference  the  moved 
section,  are  all  part  of  Basic  Aid .  Color- 
com/E  turns  the  Color  Computer  into 
a  smart  terminal  with  on-  and  off-line 
scrolling,  off-line  printing,  transfer  of 
cassette  files,  serial  printer  support  and 
full  or  half  duplex.  The  program  costs 
$49.95.  They  also  sell  a  Spectrum  Stick 
joystick  that  has  a  swivel  ball,  long  ca¬ 
ble,  sturdy  construction  and  red  LED 
on-indicator  for  $39.95  plus  $2  S&H. 
They  offer  cables  that  extend  the 
ROMpack  port  by  three  feet,  add  10 
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feet  to  the  joystick  cable,  extend  the 
cassette  recorder  or  printer/modem 
cable  by  10  feet,  and  connect  in  line 
both  a  joystick  and  their  newest  prod¬ 
uct  (so  new,  they  didn’t  even  give  us 
a  price,  but  write  them),  a  light  pen. 
An  RS232  expansion  cable  attaches 
two  devices  to  the  serial  port  at  the 
same  time,  permitting  a  printer  and 
modem  to  be  attached  in  line,  for 
$19.95.  You  can  use  your  new  equip¬ 
ment  to  access  Spectrum’s  two  bulle¬ 
tin  boards,  and  Colorcom/E  to  down¬ 
load  color  graphics:  (212)  441-3755 
and  (212)  441-3766.  Reader  Service 
No.  109. 


The  IDE  of  March 

IDE  Associates  makes  a  3.9 -inch 
Winchester  disk  with  fixed  or  remov¬ 
able  cartridges  for  the  IBM  PC.  For¬ 
matted  capacity  of  5.0  Mb  costs 
$1450  for  the  internal  mount-fixed 
cartridge  version.  The  removable  car¬ 
tridge  versions  cost  $50  more.  The 
price  includes  mounting  hardware,  ca¬ 
bles,  software  and  diagnostics  diskette, 
and  manual.  IDE  offers,  in  ten  metro¬ 
politan  areas,  what  they  claim  is  “the 
industry’s  only  free  on-site  installation 
service.”  IDE  also  sells  expansion 
memory  and  clock  cards  for  the  PC. 
For  all  their  products,  you  get  a  one- 


will  support  structures,  unions,  multi¬ 
dimensional  arrays,  and  a  few  other 
new  features,  using  the  Z80  instruc¬ 
tion  set,  and  producing  smaller,  quicker 
code.  This  will  be  offered  as  a  $  1 2  up¬ 
grade  to  current  users.  A  version  for 
the  IBM  PC  (PC  DOS)  will  also  be  re¬ 
leased  at  that  time.  The  Code  Works 
also  offers  what  they  call  the  “original” 
Small-C  by  Ron  Cain  for  $19.95,  a 
much  smaller  subset  of  C,  with  a  mini¬ 
mal  assembly-language  I/O  library  and 
an  1 1  -page  manual.  It  needs  48K.  Add 
$3.50  shipping  in  U.S.  and  Canada,  or 
$15  elsewhere,  and,  in  California,  6% 
sales  tax.  The  Code  Works  charges  no 
license  fees  for  programs  created  on  its 
compilers  and  libraries.  Reader  Service 
No.  117. 


Flying  a  Simulator? 

Simulating  Flying? 

Now  you  can  do  your  armchair 
flying  —  from  the  armchair  facing  your 
computer,  or  flying  by  the  seat  of 
your  pants  —  without  leaving  your  ter¬ 
minal.  Flight  Simulator  by  Microsoft 
for  the  IBM  PC  is  for  novice  to  experi¬ 
enced  pilots.  As  your  skill  increases, 
you  add  various  conditions,  such  as 
time  of  day,  cloud  cover,  season,  wind 
shear,  trim,  carburetor  icing,  fuel  usage, 


year  return-to-factory  warranty,  or,  in 
any  of  the  ten  areas,  the  option  to 
convert  the  warranty  to  a  fixed- price 
on-site  maintenance  agreement.  Read¬ 
er  Service  No.  111. 


More  Memory  at  Less  Price 
for  Chipmunks 

Expand  memory  on  HP’s  Series 
200  (the  9826  and  9836  68000-based 
computers  known  affectionately  in 
house  as  “Chipmunk,”  and  the  new 
9816  personal  “home”  computer) 
with  Eventide’s  WKBP-4  256K  mem¬ 
ory  expansion  board.  At  $749,  it 
costs  “hundreds”  less  than  HP’s 
equivalent.  You  can  add  half  a  mega¬ 
byte  to  the  98 1 6  for  under  $  1  ? 00,  and 
over  two  megabytes  to  the  9826  and 
9836  for,  they  say,  “less  than  $5200.” 
I’m  not  sure  how  they  perform  this 
mathematical  feat,  unless  they  offer 
discounts  for  eight  boards  ....  Read¬ 
er  Service  No.  113. 


Altos  Talks  to  Other  CP/Ms 

InterComm  from  Acquis  Data 
transfers  files  between  an  Altos  and 
other  CP/M  computers.  Included  is  a 
module  to  communicate  with  bulletin 
boards  and  public  data  bases  like  Com¬ 
puServe,  Dow  Jones,  and  The  Source. 


and  even  radio  navigation.  The  screen 
displays  an  “out-the-window”  3-D 
perspective  view  with  full  instrumenta¬ 
tion.  You  have  real-time  control  of 
the  plane  (a  single -engine  Cessna  182) 
in  several  flight  conditions,  and  data 
that  simulate  twenty-three  airports  in 
four  parts  of  the  country  (Seattle,  LA, 
Chicago,  and  New  England).  You  also 
get  British  Ace,  a  World  War  I  combat 
game  that  test  your  flying  skill  and 
strategy  against  enemy  biplanes  defend¬ 
ing  territory  that  you  must  bomb. 
You’ll  need  a  PC  with  PC- DOS,  color/ 
graphics  card,  64K,  one  disk  drive,  and 
a  monitor  (they  recommend  the  stan¬ 
dard  composite  color  monitor,  but 
you  can  use  black-and-white  or  RGB). 
$49.95.  Reader  Service  No.  121. 


Legal  Copy  Service 

Port -A- Soft  (formerly  Disk  Copy 
Service)  converts  disks  between  several 
formats,  to  or  from  5!4-  or  8-inch, 
single-,  double-,  or  quad-density,  in 
formats  of  various  operating  systems 
and  many  popular  computers,  for  $5 
to  $15  per  diskette,  and  copies  after 
conversion  for  $2.50  each.  Reader 
Service  No.  119. 


For  $175,  you  get  two  diskettes,  man¬ 
ual,  and  communications/null  modem 
cable.  InterComm  is  also  available  for 
many  other  CP/M  computers.  Reader 
Service  No.  115. 


If  The  Code  Works,  Use  It 

Version  2.0  of  the  Q/C  compiler 
for  CP/M,  from  The  Code  Works,  sup¬ 
ports  a  large  subset  (all  but  float  and 
long  data  types,  multidimensional 
arrays,  structures,  sizeof,  typedef,  and 
casts)  of  the  C  language,  compatible 
with  Bell  Labs’  UNIX  7  C,  and  in¬ 
cludes  a  library  of  over  50  I/O  func¬ 
tions.  Q/C  produces  true  native  code 
for  Z80  or  8080  for  Microsoft’s  M80 
assembler  or  for  Digital  Research’s 
ASM  or  MAC.  Assembly  language 
functions  can  be  included  in  programs. 
With  M80,  programs  can  be  compiled 
as  separate  modules  and  Microsoft’s 
L80  linker  can  be  used  to  combine 
the  relocatable  files.  Full  source 
code  for  compiler  and  library  are  in¬ 
cluded,  as  well  as  a  comprehensive, 
beautifully  typeset  138 -page  manual. 
You’ll  need  a  56K  CP/M,  and  either 
soft-sectored  8 -inch  single-density  or 
hard-sectored  514-inch  Micropolis 
Mod-II  format  double-density  (Vector 
Graphics  MZ)  disk.  The  Q/C  disk  costs 
$95.  Look  for  version  3.0  soon,  which 
i _ 


Other  Stuff 

Do  you  own  or  have  access  to  a 
DEC  system  with  RT-11,  TSX,  or 
TSX-Plus?  Do  Z80  software  develop¬ 
ment  on  it  with  SATEC  Systems’  Z80 
Cross  Assembler,  available  for  $200  on 
paper  tape,  8 -inch  floppy,  or  source 
listing.  Reader  Service  No.  123. 

Here’s  your  chance  to  see  if  you 
are  smarter  than  a  computer  at  word 
|  games.  Wordtrix  from  Insoft  for  the 
IBM  PC  has  you  compete  against  the 
machine  to  find  words  in  a  random 
}  grid  of  letters.  The  computer  brings  its 
own  dictionary  (how  can  you  argue 
with  the  guy  who  brings  the  bat?) 
and  plays  on  several  levels.  $34.95. 
j  Reader  Service  No.  125. 

Learn  about  protecting  software, 
copyrighting  programs,  writing  and 
negotiating  your  own  licensing  con¬ 
tracts,  limiting  liability,  and  other  legal 
considerations  for  programmers  and 
software  publishers  in  Legal  Care  for 
Your  Software  by  Attorney  Daniel 
Remer,  published  and  distributed  by 
Nolo  Press.  Reader  Service  No.  127. 
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(Continued  from  page  1 1 ) 

Since  a  number  of  you  may  be  wondering 
where  your  package  is,  we  thought  that 
you  might  be  interested  in  the  following 
letter  which  we  recently  received  from 
JRT  Systems  concerning  late  deliveries. 
We  see  that  the  letter  does  not  mention 
adjustments  to  any  of  the  bugs  that  have 
been  noted,  but  we  understand  that  JRT 
has  a  new  version  which  they  expect  to 
begin  shipping  in  mid-February. 

Dear  Editor, 

We  are  having  delays  in  the  shipping 
of  JRT  Pascal  to  our  customers.  I  have 
received  a  number  of  letters  from  custo¬ 
mers  who  are  very  concerned  about  this. 
Similar  letters  have  been  sent  to  the  edi¬ 
tors  of  the  magazines  in  which  JRT  Sys¬ 
tems  advertises. 

It  has  always  been  our  policy  to 
immediately  cancel  any  order  on  request 
or  make  an  immediate  refund  if  payment 
has  been  processed  and  shipment  not  yet 
made. 

As  of  today  we  have  shipped  10,000 
Pascals  and  have  7,000  orders  on  backlog. 
About  6,000  of  those  are  less  than  six 
weeks  old.  A  six  to  eight  week  shipping 
delay  is  not  unprecedented  in  the  com¬ 
puter  industry,  but  it  is  not  acceptable  to 
JRT  Systems. 

How  did  this  backlog  develop  and 
what  am  I  doing  to  correct  it?  In  May  of 
1982,  I  cut  the  price  of  JRT  Pascal  from 

$295  to  $29.95.  I  tested  this  formula  by 
“mass”  mailings  of  100  then  400  then 
1000  brochures.  Sales  response  was  excel¬ 
lent  —  10%  to  15%  —  on  the  early  mail¬ 
ings.  I  was  able  to  very  rapidly  expand 
the  mass  mailings  and  advertising  leading 
to  these  approximate  sales  figures:  May  - 
100,  June -350,  July -  700,  August - 
1400,  September  -  2000,  October  -  4000, 
November  -  3000,  December  -  5000. 

In  August  JRT  Systems  moved  from 
my  home  to  a  small  office  on  Irving  Street 
in  San  Francisco.  By  October  this  office 
was  severely  crowded  with  six  people, 
three  phones  and  two  computers.  In  mid- 
December  we  leased  6,000  square  feet  of 
space  in  Mill  Valley.  The  shipping  depart¬ 
ment  has  now  moved  from  Irving  into 
1,600  square  feet  of  the  new  space.  In  the 
past  two  weeks,  the  shipping  staff  has 
grown  from  one  to  four  full-time  people. 
In  this  same  period,  we  completed  instal¬ 
lation  of  a  sophisticated  set  of  new  ship¬ 
ping  programs  which  automates,  logs  and 
validates  every  aspect  of  the  shipping 
operation.  Last  week  we  exceeded  500 
Pascal  shipments  per  day.  With  our  new 
system  we  can  exceed  1000  per  day. 

We  still  have  delays  in  obtaining 
copied  diskettes  rapidly  enough,  especial¬ 
ly  in  554”  formats.  Changes  planned  for 
the  near  future  will  eliminate  this  prob¬ 
lem. 


In  short,  the  delay  in  shipping  JRT 
Pascal  is  due  to  the  staggering  sales 
growth.  We  are  moving  as  fast  as  possible 
to  expand  production  capacity. 

Sincerely, 

J.  R.  Tyson,  President 
JRT  Systems 
550  Irving  Street 
San  Francisco,  CA  94122 
(415)  566-5100 

A  Few  Suggestions 

Dear  Editor, 

First,  I  want  to  address  the  contents 
of  the  columns,  Of  Interest,  CP/M  Ex¬ 
change,  and  16-Bit  Software  Toolbox. 
The  first  of  these  columns  contains  infor¬ 
mation  which  I  think  most  DDJ  readers 
find  redundant.  I  think  that  DDJ  should 
devote  its  spape  to  articles  and  not  to 
condensed  press  releases  which  may  be 
found  in  BYTE  or  any  number  of  other 
journals.  Conversely,  I  think  that  the  sec¬ 
ond  and  third  columns  have  a  place  in 
DDJ.  However,  I  think  that  they  need 
some  changes.  CP/M  Exchange  needs  to 
deal  with  topics,  not  just  contain  an¬ 
nouncements.  I  would  like  to  see  the 
columnist  find  topics  of  interest  and  dis¬ 
cuss  them  instead  of  continually  referring 
to  RCP/M  related  announcements.  Finally, 
I  think  that  16-Bit  Software  Toolbox 
should  stay  away  from  press  releases  and 
concentrate  on  one  (or  at  most  two) 
topics  per  month.  This  would  allow  the 
columnist  to  explore  the  topics  more 
carefully. 

Second,  I  would  like  to  reiterate  my 
comment  concerning  the  overall  quality 
of  the  journal.  I  strongly  believe  that 
good  material  still  appears  in  DDJ.  How¬ 
ever,  it  is  wise  to  remember  that  good 
material  appeared  in  quantity  even  when 
the  magazine  ran  with  no  advertisements. 
One  would  expect  quality  to  increase  and 
not  for  medipcrity  to  become  a  serious 
threat  once  ads  were  included. 

Finally,  I  would  like  to  make  one 
additonal  comment.  I  think  that  articles 
should  be  rated  by  user  reaction,  and 
remuneration  based  thereon.  This  is 
already  done  by  BYTE. 

Sincerely, 

Anthony  Skjellum 
1695  Shennandoah  Road 
San  Marino,  CA  91108 

Keeping  Us  Honest 

Joe  Williams  called  in  to  let  us  know 
that  we  had  a  minor  error  in  the  Small-C 
compiler  listing  in  the  January  1 983  issue. 
The  listing  portion  at  the  top  of  page  63 
should  have  preceeded  the  listing  portion 
on  the  top  of  page  62,  not  followed  it. 
-  Ed. 
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const 

N=12;  V=4j 


:  array  (1.8 )  of  integer  ; 

:  array  (1.12)  of  integer; 

I :  integer 
egin 

B(  1  ):=  010101010101 ;  B 
=  111100001111;  B 
=  101010101010;  E 
=  OOOOI  i"11  OOOO;  I 


B(3) 

B(5) 
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LETTERS 


Xanadu  Re-Edited 

Dear  Dr.  Dobb’s: 

Thank  you  very  much  for  publishing 
our  piece  on  the  Xanadu  Hypertext  Sys¬ 
tem  in  the  January  issue  of  Dr.  Dobb’s. 
While  we  were  delighted  to  get  word  of 
our  system  in  front  of  an  audience,  the 
editorial  process  somehow  managed  to 
introduce  a  couple  of  errors  which  deserve 
correction. 

First  of  all,  the  article  says  that  the 
Xanadu  System  is  a  currently  available 
product.  This  is  not  entirely  correct,  and 
that  was  not  how  we  wrote  it.  We  are 
now  marketing  the  system  for  large 
scale  commercial  applications,  but  we  are 
doing  so  solely  as  a  part  of  custom  systems 
being  produced  on  spec.  While  the  system 
does  work,  it  is  as  yet  underdevelopment, 
and  several  more  months  of  effort  will  be 
required  before  it  will  be  a  marketable 
product  available  “off  the  shelf.”  We  are 
still  working  on  various  more  advanced 
portions  of  the  system,  including  the 
versioning  facility  and  historical  trace.  We 
have  been  giving  demonstrations  regularly 
and  are  now  looking  for  our  first  major 
customer.  We  are  prepared  to  offer 
custom  systems  for  applications  such  as 
engineering  project  management,  software 
maintenance  and  source  code  manage¬ 
ment,  and  business  document  handling. 
We  are  currently  quoting  delivery  times 
of  six  months  to  a  year  for  such  systems. 


Anyone  interested  should  contact  us  for 
details,  quotes  or  demonstrations. 

Second,  the  article  is  credited  to  me. 
While  I  was  the  person  who  sent  you  the 
Xanadu  material,  the  piece  that  you 
selected  for  publication,  out  of  the  two- 
hundred  or  so  pages  that  we  sent,  was 
written  by  our  Executive  Vice  President, 
Chip  Morningstar.  Since  it  was  he  who 
put  in  the  hours  writing  it,  he  should  get 
the  credit  for  it. 

We  would  like  to  talk  with  anyone 
interested  in  developing  frontend  systems. 
A  preliminary  protocol  for  frontend/ 
backend  interaction  is  available  for  the 
asking  to  anyone  seriously  contemplating 
frontend  work.  Our  frontend  develop¬ 
ment  currently  takes  place  on  our  SUN 
(trademark  SUN  Microsystems  Inc.)  work¬ 
station  in  C  under  UNIX  (trademark  Bell 
Laboratories).  A  copy  of  the  current 
frontend  is  also  available  to  anyone 
seriously  interested.  Most  of  our  energies 
have  been  devoted  to  getting  the  backend 
working,  and  there  are  a  lot  of  interesting 
human-machine  interface  problems  yet 
to  be  attacked.  Again,  interested  parties 
should  contact  XOC  for  details. 

Thank  you  again. 

Sincerely, 

Roger  Gregory,  President 

XOC 

P.O.  Box  7615 

Ann  Arbor,  MI  48107 


Mr.  Peters’  letter  was  specifically 
concerned  with  JRT  Pascal  but,  as  an 
aside,  included  the  comment  that  “Pascal 
includes  what  is  probably  the  worst  pro¬ 
gramming  practice  known  to  modern  sci¬ 
ence:  running  once  through  a  loop  before 
making  any  tests  (REPEAT.  .  .  UNTIL).” 
This  comment  pushed  one  of  my  hot  but¬ 
tons.  That  alone  would  not  have  sparked 
a  letter  except  that  this  particular  hot 
button  has  happened  to  be  exercised  re¬ 
peatedly  in  the  last  few  months. 

REPEAT.  .  .UNTIL  is  not  a  program¬ 
ming  practice  at  all.  It  is  a  tool  provided 
by  the  language  designer  to  be  used,  or 
not  used,  as  may  be  deemed  appropriate 
by  programmers  working  in  the  language. 
This  tool,  like  any  other,  may  be  left  to 
rust  in  the  toolbox  or  it  may  be  used  as 
needed  when  its  use  is  deemed  appropri¬ 
ate. 

One  good  example  of  an  appropriate 
use  of  this  tool  is  provided  by  Kernighan 
and  Ritchie  in  The  C  Programming  Lan¬ 
guage.  In  their  itoa(n,s)  function,  it  is  de¬ 
sired  to  convert  an  integer,  n,  to  an  ASCII 


OK  to  Repeat 

Dear  Doc, 

I’m  writing  this  on  the  last  day  of 
1982.  It  has  been  a  couple  of  years  since 
I  last  wrote,  but  a  passing  comment  in 
J.  H.  Peters’  letter  in  the  January  1983 
issue  has  moved  me  to  the  tyepwriter. 


EDITORIAL 


Welcome  to  our  second  ninety-six  page  issue!  We  are 
pleased  to  bring  you  more  editorial  pages  than  ever,  and 
expect  even  more  in  the  second  half  of  1983.  As  we  grow, 
you  will  find  more  of  the  high-quality  material  that  you 
have  come  to  expect  from  DDJ.  The  increase  in  size  will 
help  ensure  that  the  reader  forum  will  continue  to  be  pro¬ 
vided  in  our  pages.  This  is  one  of  the  things  that  separates 
us  from  the  crowd  —  the  difference  between  editors  and 
experts. 

*  *  * 

This  issue’s  CP/M  Exchange  is  the  second  of  a  two-part 
series  on  CP/M  disk  I/O.  It  marks  Gene  Head’s  last  month 
as  columnist  for  the  Exchange,  though  he  will  continue  to 
operate  his  RCP/M  system.  We  would  like  fo  thank  Gene 
for  all  his  fine  contributions  over  the  past  months  and  look 
forward  to  continued  input  from  his  Oregon  Head  Quarters. 
Gene  is  passing  the  pen  to  Bob  Blum.  No  stranger  to  DDJ 


or  to  the  Exchange,  Bob  provided  the  current  series  on  disk 
I/O,  and  he  will  begin  a  series  on  CP/M  Plus  in  the  May 
issue.  We  are  glad  to  welcome  him  aboard. 

*  *  * 

A  couple  of  months  ago  we  mentioned  the  possibility 
of  condensing  some  listings  in  order  to  highlight  exemplary 
or  instructive  sections  of  code.  The  motivation  was  to  get 
more  information  to  you,  not  less.  We  fear  this  may  have 
given  rise  to  the  misinterpretation  that  we  were  making  a 
significant  shift  toward  eliminating  listings.  Not  so!  Dr. 
Dobb’s  has  always  been  a  forum  for  software  and  program¬ 
ming  ideas.  In  keeping  with  our  tradition,  we  will,  of  course, 
continue  publishing  complete  listings.  . .  .  Are  those  sighs 
of  relief  we  hear? 

Reynold  Wiggins 
Editor 
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string  at  s.  Leading  zeroes  are  to  be  sup¬ 
pressed  unless  n  has  a  value  of  zero,  in 
which  case  a  single  ASCII  zero  should  be 
generated.  This  exceptional  case  is  neatly 
accommodated  by  passing  once  through 
the  loop  before  testing  for  a  zero  value  in  n. 

Best  regards,  and  best  wishes  in  the 
new  year. 

William  T.  Mitchell 
P.O.  Box  94978 
Schaumburg,  IL  60194 

Hardware  Help 

Gentlemen, 

I  would  like  to  see  a  hardware  article 
on  making  a  dynamic  RAM  board  using 
an  Intel  8203  dynamic  RAM  controller 
(for  64K  DRAMs)  or  8207  (for  256K 
DRAMs).  Intel  has  application  notes  on 
just  such  topics,  but  they  provide  only 
block  diagrams  (all  of  the  ICs  are  listed) 
and  I’d  like  to  see  a  complete  schematic 
of  a  working  board. 

I’ve  been  looking  for  information  on 
connecting  a  Model  33  teletype  to  my 
TRS-80  Color  Computer  and  my  Sinclair 
ZX81.  I’ve  been  able  to  find  a  general 
RS232  to  60mA  current  loop  interface 
diagram,  but  would  like  more  specific 
information  (my  Model  33  TTY  is  set  for 
20mA  current  loop).  I’m  sure  many 
people  have  used  Model  33  TTYs  as  print¬ 
ers,  but  I’ve  been  unable  to  locate  any 
(sorry  this  note  isn’t  printed!).  I’d  greatly 
appreciate  any  help  you  could  give  me  on 
this  matter  (both  hardware  and  software). 

Yours  truly, 

Timothy  J.  Mcllwee 
Rural  Route  2,  Box  462A 
Dundee,  IL  60118 

Forth  Loader  Fix 

Dear  Dr.  Dobb ’s  : 

I  encountered  some  problems  using 
the  Forth  Relocating  Loader  which  was 
published  in  your  September  1982  issue 
(No.  71).  Upon  examination,  I  found  that 
the  program  was  doing  signed  compari¬ 
sons  of  addresses  instead  of  unsigned 
comparisons  (i.e.,  using  <C  and  >  instead 
of  U<  and  U>).  I  corrected  this  in 
screens  10  and  1 1,  and  in  14  through  19, 
and  everything  worked  fine  after  that. 

Thanks,  and  keep  up  the  good  work 
on  your  magazine. 

David  J.  Sieber 
Star  Computer  Systems 
20600  Gramercy  Place 
Torrance,  CA  90501 

DIR. ASM  Problems? 

Dear  DDJ: 

DIR. ASM,  published  in  the  CP/M  Ex¬ 
change  column  in  February  1983,  proba¬ 
bly  should  not  have  been  published  at  all; 
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but  since  it  was,  it  should  have  had  the 
warning:  “Use  this  program  at  your  own 
risk.  It  is  untested.” 

I  wrote  the  program  in  response  to  a 
request  to  give  the  readers  code.  After 
hurriedly  submitting  the  untested  pro¬ 
gram,  I  found  it  to  be  machine  dependent 
in  some  cases  and  told  the  editor  about 
the  problems.  I  was  assured  a  disclaimer 
would  be  included,  and  was  told  that  the 
code  was  a  good  starting  point  for  a  bet¬ 
ter  directory  utility  and  maybe  a  chal¬ 
lenge  to  hackers  to  get  operating  on  spe¬ 
cific  systems. 

Since,  then,  I  found  SD-41.ASM  in 
the  public  domain.  This  is  a  far  better 
directory  utility  than  DIR. ASM  with 
more  features  and  faster  execution  not  to 
mention  fewer  (zero)  known  bugs. 

To  those  trying  to  get  DIR. ASM 
working,  I  suggest  you  scrap  it  and  get  a 
copy  of  SD-41.ASM  (and  SD-41.DOC) 
from  any  RCP/M  system.  I  apologize  for 
any  inconvenience  and  in  the  future  will 
not  make  the  mistake  of  releasing  code 
without  complete  field  testing. 

Sincerely, 

Gene  Head 
Head  Quarters 
2860  NW  Skyline  Drive 
Corvallis,  OR  97330 

Hi -Res  Vector  Display  Revisited 

Dear  DDJ: 

Following  my  letter  in  the  September 
1982  issue  (DDJ  No.  71),  I  have  received 
many  letters  concerning  the  color  graphics 
display  I  described  therein.  I  cannot  spare 
the  time  to  give  individual  replies  but  do 
intend  to  write  up  the  system  for  pub¬ 
lication  when  it  is  finally  perfected.  There 
is  still  a  lot  of  work  to  do  before  it  can  be 
confidently  offered  to  others  to  duplicate, 
mainly  in  cutting  the  enormous  cost  -  e.g., 
the  special  CRT  used  costs  over  $1000  on 
a  one-off  basis. 

Have  other  68000  users  any  ideas  on 
standardization  of  memory  maps,  disk 
formats,  etc.  to  allow  software  inter¬ 
change?  There  seem  to  be  no  standards  at 
all  at  the  moment  and  I  fear  we  will  have 
a  similar  situation  to  that  which  now  ap¬ 
plies  to  the  6502,  with  many  machines 
having  no  interchangeability  of  software 
whatever.  My  own  choice,  for  what  it’s 
worth,  is  to  place  ROM  between  000000 
and  00FFFF,  I/O  ports  from  010000  to 
01FFFF  and  RAM  in  the  rest  of  the  ad¬ 
dress  space.  I  use  the  IEEE-696  S-100 
bus,  which  is  very  suitable  for  this  system 
and  gives  good  hardware  interchangeabili¬ 
ty  —  I  have  processor  boards  with  other 
CPUs  which  I  can  use  when  I  need  to. 

Finally,  does  anyone  have  any  infor¬ 
mation  concerning  a  Wangco  8201  flop¬ 


py  disk  controller  board  and  an  MFE 
model  250B  digital  cassette  deck?  Wangco 
no  longer  make  the  former  and  cannot 
supply  any  information  and  I’ve  no  idea 
who  MFE  are  at  all.  Any  info  would  be 
very  welcome. 

Sincerely, 

Greg  Trice 

1131  Sandhurst  Circle,  #111 
Scarborough,  Ontario 
Canada  M1V1V5 

Ruzinsky  Re -Corrected 

Dear  Readers, 

Steven  Ruzinsky  wrote  in  to  tell  us 
that  a  production  error  had  caused 
an  incorrect  correction  to  his  equations 
on  page  10,  column  3  of  the  March  issue. 
Lest  any  be  confused  by  the  resulting 
“non-equation,”  the  text  should  have 
read: 

Let  U  =  Angle 
SI  =  .9999999999999999 
VI =  SI *[FABS(FABS[FPREM 
(U,2  *  PI)  ]  -  PI) -PI/2] 

COS(U)  =  Y(V)/FSQRT(  X(V)*X (V) 
+  Y(V)*  Y(V) ) 

Our  apologies  to  Mr.  Ruzinsky  and  any¬ 
one  who  was  inconvenienced. 

The  Editor 
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CP/M  EXCHANGE 


by  Gene  Head 


Bob  Blum  will  take  over  this  column 
beginning  next  month.  Bob  has  brought 
considerable  technical  expertise  with  this 
two-part  series  on  the  CP/M  disk  and  plans 
to  begin  a  series  on  CP/M+  next  month. 

Take  the  time  to  read  and  re-read  this 
month’s  column.  It’s  all  meat  and  no  fat 
but  you  may  need  a  pencil  and  paper  to  do 
some  quick  calculations.  It  was  a  real  eye- 
opener  for  me.  Bob  knows  his  stuff! 

Last  month  we  reviewed  how  CP/M 
allocates  and  maintains  disk  space.  Our 
discussion  this  month  will  continue  by 
exploring  first  the  file  control  block  (FCB) 
and  then  the  various  BIOS  tables  used  to 
describe  the  disk  system  and  their  inter¬ 
action  with  CP/M. 

When  accessing  a  disk  file  through 
BDOS,  a  properly  initialized  FCB  must  be 
used.  The  open  routines  use  the  file  name 
and  type  fields  as  the  search  argument  for 
the  desired  file.  Upon  a  successful  match, 
the  allocation  information  from  the 
stored  extent  is  copied  into  the  FCB  for 


future  file  operations.  During  input/out¬ 
put  (I/O),  various  fields  of  the  FCB  are 
used  to  maintain  an  updated  copy  of  the 
file’s  status. 

When  writing  to  a  file,  if  the  FCB’s 
addressing  range  is  exceeded  or  the  file  is 
closed,  the  current  FCB  is  written  to  the 
disk  directory  after  the  last  four  bytes  are 
discarded.  This  truncation  maintains  com¬ 
patibility  with  earlier  releases  of  CP/M 
and  also  eliminates  unneeded  information. 
It  should  be  noted  that  the  names,  FCB 
and  extent,  can  be  used  interchangeably, 
although  FCB  typically  refers  to  the 
memory  resident  file  control  block,  while 
extents  are  disk  resident. 

Referring  to  Figure  1 ,  the  first  byte 
of  the  FCB,  DR,  has  a  dual  purpose  de¬ 
pending  on  whether  the  FCB  is  memory 
or  disk  resident.  When  the  FCB  is  in 
memory,  the  DR  entry  (when  non-zero) 
designates  which  disk  drive  is  to  be  auto- 
selected.  After  the  FCB  is  written  to  disk, 
the  DR  entry  reflects  the  file  user  number. 
The  next  1 1  bytes  contain  eight  bytes  for 


the  file  name  and  three  bytes  for  the  file 
type.  The  high-order  bits  of  the  first  two 
bytes  of  the  file  type  are  used  to  indicate 
if  the  file  is  read-only  or  a  system  file. 
Only  two  of  the  next  three  bytes  are  im¬ 
portant  to  this  discussion.  The  first  byte. 
EX,  contains  the  current  extent  number 
in  the  range  of  0  to  31.  If  the  file  expands 
beyond  32  extents,  the  EX  byte  is  zeroed 
and  the  third  byte,  EC,  is  incremented 
These  two  bytes  can  be  visualized  as  con¬ 
taining  a  nine-bit  number  with  the  EX 
byte  containing  the  low- order  five  bits 
and  the  high-order  four  bits  present  in 
the  EC  byte.  To  verify  the  maximum  file 
size  of  8,388,608,  multiply  each  extent 
of  16,384  bytes  by  5  1 2  extents. 

Another  way  to  view  the  association 
between  these  two  fields  is  that  the  EX 
byte  contains  the  extent  number  within  a 
group  contained  in  the  EC  byte.  Continu¬ 
ing  along  to  the  remaining  fields,  as  each 
128-byte  sector  is  written,  the  record 
count  byte,  RC,  is  incremented  by  one 
until  128  is  reached.  When  this  occurs, 
the  FCB  is  written  into  the  directory  and 
a  new  FCB  is  automatically  prepared  for 
additional  file  operations.  We  can  now 
verify  that  each  extent  can  address  16,384 
bytes  by  multiplying  128  sectors  by  128 
bytes  per  sector.  The  allocation  map  area 
of  the  FCB,  AM,  provides  room  for  16 
bytes  of  data  allocation  group  numbers. 
Each  allocation  group  number  can  be 
either  one  or  two  bytes  in  length  depend¬ 
ing  on  how  many  allocation  groups  are 
contained  on  the  disk.  Further  attention 
will  be  given  to  this  later  in  the  discussion 
on  disk  parameter  blocks.  The  remaining 
four  bytes  of  the  FCB  are  used  for  sequen¬ 
tial  and  random  access  into  a  file  and  are 
left  for  independent  study. 

As  delivered  by  Digital  Research, 
CP/M  is  configured  for  the  MDS-800. 
which  is  not  in  common  use.  For  that 
reason  we  will  assume  that  CP/M  is  un¬ 
configured  as  distributed.  Before  studying 
how  to  configure  CP/M  for  a  particular 
disk  system  it  may  be  helpful  to  examine 
an  overview  of  all  the  integral  parts  of  the 
BIOS.  Figure  4  (page  12)  shows  us  that 
the  CBIOS  begins  with  a  series  of  sixteen 
jumps  followed  by  one  disk  parameter 
header  (DPH)  for  each  disk  drive  attached 
to  the  system.  The  DPH  contains  address 
pointers  to  various  other  tables  that  com¬ 
pletely  describe  the  disk  formats  that  can 
be  used  on  this  particular  system. 

From  Figure  2  (page  10),  the  first  field 
in  the  DPH,  XLT,  is  a  two-byte  pointer  to 


FILE 

CONTROL  BLOCK 

OFFSET 

SYMBOL 

BYTES 

DESCRIPTION'S 

0 

DR 

1 

Drive  number: 

0  =  Def  aul t  dr i ve 

1  =  Auto  select  drive  A 

16  =  Auto  select  drive  P 

1 

FN 

8 

File  name  in  upper  case  ASCII.  Padded 
on  right  with  blanks  if  necessary. 

9 

FT 

File  type  in  upper  case  ASCII.  High 
order  bits  contain  additional 
information. 

BYTE  9=1  Read  only  file 

BYTE  10  =  1  System  file.  File  will 
not  be  listed  during  a  directory 
list. 

12 

EX 

1 

Number  of  current  extent  in  use. 

13 

WA 

1 

Workarea. 

14 

EC 

1 

When  extent  number,  EX,  exceeds  32 
this  byte  acts  as  an  overflow  area. 

15 

RC 

1 

Record  count.  Number  of  128  byte 
records  contained  in  this  extent. 

16 

AM 

16 

Allocation  map.  Allocation  group 
number  storage  area. 

32 

CR 

1 

Current  record.  Number  of  record 
currently  be  accessed. 

33 

RR 

3 

Random  record.  Record  number  to  be 
used  for  accessing  the  file 
r andoml y . 

Figure  1. 
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the  physical  sector  translation  table. 
Through  this  table  it’s  possible  to  translate 
a  logical  sector  to  its  physical  equivalent. 
Many  of  today’s  systems  allow  different 
disk  formats  to  be  used  interchangeably 
on  the  same  drive.  For  this  reason,  when 
logging  in  a  disk,  the  BIOS  will  probably 
access  a  known  part  of  the  disk  to  deter¬ 
mine  the  format  and  place  the  address  of 
the  corresponding  disk  parameter  block 
into  DPB  and  the  appropriate  translation 
table  address  into  XLT. 

The  next  two  bytes  are  used  for  a 
workarea  by  BDOS  followed  by  a  two- 
byte  pointer,  DIRBUF,  to  an  area  of 
memory  128  bytes  long  which  is  used  for 
directory  operations.  All  DPHs  can  point 
to  the  same  DIRBUF  because  only  one 
directory  operation  will  be  active  at  a 
time.  For  example,  when  a  file  is  opened, 
the  directory  is  read  into  the  buffer 
pointed  to  by  DIRBUF  one  sector  at  a 
time.  If  the  desired  file  is  found,  an  index 
number  is  returned  to  the  requester  so 
that  additional  information  can  be  ex¬ 
tracted.  CSV  points  to  a  workarea  used 
for  calculation  of  the  directory  checksum. 
This  checksum  is  used  to  detect  when  a 
disk  has  been  changed  without  a  warm 
start.  Each  disk  drive  must  have  its  own 
CSV  workarea.  The  DPH  ends  with  a  two- 
byte  pointer,  ALV,  to  a  savearea  which 
will  contain  the  allocation  map  after  a 
disk  is  logged  in.  A  separate  ALV  savearea 
must  be  reserved  for  each  disk  drive  on 
the  system. 

The  disk  parameter  block  (see  Figure 
3)  contains  all  the  information  necessary 
to  describe  the  disk  format  in  use.  The 
first  entry,  SPT,  contains  the  total  number 
of  logical  sectors  per  track.  This  number 
may  not  equal  the  number  of  physical  sec¬ 
tors  actually  written  on  each  track.  For  ex¬ 
ample.  TARBELL  double-density  format 
uses  sixteen  512-byte  sectors  per  track. 
Since  there  are  four  128-byte  sectors  per 
physical  sector,  SPT  would  contain  64. 

Before  discussing  the  next  three 
fields,  a  few  decisions  must  be  made. 
First,  decide  how  large  the  data  allocation 
block  should  be.  On  systems  where  the 
total  capacity  of  any  one  disk  is  less  than 
225K,  block  sizes  from  IK  to  16K  can  be 
used.  On  larger  capacity  formats  you  are 
limited  to  selecting  block  sizes  2K  and 
larger.  Tradeoffs  between  block  sizes  are 
subtle.  If  you  consistently  create  small 
files,  a  smaller  block  size  will  probably 
be  best  suited  to  your  needs.  Larger  block 
sizes  have  the  advantage  of  keeping  more 
sequential  data  available  without  exces¬ 
sive  head  movement. 

Next  determine  how  many  data 
blocks  can  be  allocated.  This  is  a  function 
of  the  total  capacity  of  the  disk  format 
being  used  minus  the  number  of  reserved 
system  tracks  divided  by  the  data  block 
size.  This  value  is  placed  in  DSM. 

With  these  decisions  made,  the  tables 
■i>  5  (page  12)  are  used  to  •Provide 


values  for  BSH,  BLM,  and  EXM.  The 
extent  mask  value  further  redefines  how 
much  storage  can  actually  be  addressed 
by  each  FCB.  For  example,  disks  with 
less  than  255  data  allocation  groups  only 
require  one  byte  for  each  group  pointer. 
If  the  allocation  groups  are  2K  in  size 
then  only  eight  bytes  are  used  for  each 
16K  addressed  leaving  eight  bytes  of  allo¬ 
cation  map  unused  in  the  FCB.  By  coding 
EXM  with  1,  two  logical  extents  can  be 
stored  in  each  physical  FCB  extending  its 
addressing  range  to  32K. 


The  situation  becomes  more  confused 
when  there  are  more  than  255  allocation 
groups.  In  this  case  each  pointer  requires 
two  bytes.  In  any  case  the  tables  in  Figure 
5  will  provide  the  proper  entries  to  be 
used.  The  total  number  of  directory  en¬ 
tries,  DRM,  is  also  a  function  of  the  data 
block  size.  Each  directory  entry  is  32 
bytes  long.  If  the  data  block  size  is  IK 
then  32  directory  entries  will  be  contained 
in  each  block. 

T ypically  two  data  blocks  are  reserved 
for  directory  use.  DRM  would  then  be 


DISK 

PARAMETER  HEADER 

OFFSET 

SYMBOL 

BYTES 

DESCRIPTION  S 

0 

XLT 

2 

Address  of  the  logical  to  physical 
sector  translation  table. 

2 

6 

BDOS  workarea. 

8 

DIRBUF 

2 

Address  of  a  one  sector  workarea 
used  for  directory  operations. 

10 

DPB 

2 

Address  of  the  disk  parameter  block 
for  this  drive. 

12 

CSV 

2 

Address  of  a  workarea  used  to 
calculate  the  directory  checksum  to 
detect  changed  disks. 

14 

ALV 

2 

Address  of  a  savearea  used  for  this 
drives  allocation  map. 

Figure  2. 

DISK 

PARAMETER  BLOCK 

OFFSET 

SYMBOL 

BYTES 

DESCRIPTION'  S 

o 

SPT 

2 

Total  number  of  128  byte  sectors 
per  track. 

2 

BSH 

1 

Data  allocation  block  shift 
factor  as  determined  by  the  data 
block  allocation  size. 

3 

BLM 

1 

Data  allocation  block  mask. 

4 

EXM 

1 

Extent  mask  determined  by  the 
number  of  data  blocks  allocated 
and  the  data  allocation  block 
size. 

5 

DSM 

2 

Total  number  of  data  blocks 
allocated  to  this  drive. 

7 

DRM 

2 

Total  number  of  directory 
entries  allocated  for  this  drive 
minus  1. 

9 

ALO 

1 

Table  of  16  bits  set  on  from 

AL1 

1 

left  to  right  indicating 
allocation  groups  reserved  for 
directory  usage. 

1 1 

CKS 

2 

Size  of  the  directory  check 
vector . 

13 

OFF 

2 

Track  offset  to  logical  track 
zero. 

Figure  3. 
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coded  with  63.  The  decision  on  how 
many  data  blocks  to  reserve  for  the  direc¬ 
tory  is  reflected  in  entries  ALO  and  AL1. 
Given  that  two  data  blocks  are  reserved 
for  directory  use,  the  two  high- order  bits 
of  the  16- bit  quantity  formed  by  com¬ 
bining  ALO  and  AL1  would  be  set  on. 
This  value  is  used  when  a  new  disk  is 
logged  in  to  mask  the  allocation  vector 
table  to  prevent  any  damage  to  the  direc¬ 
tory  data  blocks.  The  next  entry,  CKS, 
should  contain  the  total  number  of  direc¬ 
tory  entries  in  use.  Each  time  a  disk  is 
selected  after  it  has  been  logged  in,  the 
directory  is  checked  against  the  stored 
checksum  to  determine  if  the  disk  has 
been  changed  without  a  warm  start.  If  a 
hard  disk  is  in  use  it  is  not  necessary  to 
provide  for  directory  checking. 


By  using  the  information  contained 
in  the  disk  parameter  block,  you  can 
move  about  the  disk  system  at  will.  To 
calculate  the  starting  track  and  sector 
numbers  from  a  known  allocation  group 
number  requires  only  a  few  steps.  First 
multiply  the  group  number  by  BLM  plus 
one.  This  can  easily  be  done  by  shifting 
the  group  number  left  the  number  of 
times  contained  in  BSH.  This  results  in 
supplying  the  actual  sector  number  as  if 
all  the  sectors  were  sequentially  num¬ 
bered.  Now  divide  the  result  by  SPT  and 
add  OFF  to  the  quotient.  The  remainder 
is  the  starting  sector  number  while  the 
quotient  is  the  starting  track  number. 

To  calculate  a  group  number  with 
known  track  and  sector  numbers  does  not 
require  any  more  effort.  Subtract  OFF 


from  track  then  multiply  the  track  num¬ 
ber  by  SPT  and  add  the  sector  number  to 
the  quotient.  Now  divide  the  quotient  by 
BLM  plus  one. 

In  a  very  short  time  we  have  covered 
the  same  material  that  has  been  presented 
in  a  number  of  books.  I  suggest  that  you 
use  the  information  presented  here  while 
reviewing  a  BIOS  listing.  Next  month  the 
features  of  CP/M  Plus  will  be  compared 
to  those  provided  by  CP/M  2.x. 


12 
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RECLAIM 

A  File  Reclamation  Utility 
for  Destroyed  Directories 


Editor’s  note:  The  author  informed  us 
that  he  wrote  this  utility  in  self-defense, 
after  an  errant  program  had  destroyed  his 
directory  of  a  megabyte  of  important 
files.  It  took  him  about  fifty  man-hours, 
including  the  writing  of  the  program,  to 
completely  recover  all  those  files.  The 
source  code  for  this  utility  is  written  for 
use  with  Ron  Cain’s  version  1  of  the 
Small-C  compiler.  It  has  not  yet  been 
tried  with  J.  E.  Hendrix’s  upgrade,  Small  - 
C  version  2  (see  DDJ  Nos.  74  and  75), 
but  it  should  be  upwardly  compatible. 

This  utility  is  available  from  the 
author  on  8-inch,  SSSD,  CP/ M- format 
diskettes  for  $30,  which  include  the 
source  code,  additional  documentation 
on  use  and  configuration,  and  an  execut¬ 
able  version  (for  CP/M  2.2).  For  other 
formats,  send  inquiries  to  the  author. 

Many  people  who  make  frequent  use 
of  microcomputers  have  had  the 
disheartening  experience  of  loss  of 
data  in  a  disk  system.  This  can  be  due  to 
operator  error,  program  error,  or  hard¬ 
ware  malfunction.  Experienced  people 
usually  will  not  offer  any  sympathy  to 
those  who  lose  important  data  because  it 
should  have  been  backed  up  on  some  re¬ 
movable  media.  Despite  this  common- 
sense  rule,  people  still  fall  prey  to  various 
time  and  productivity  pressures  and  occa¬ 
sionally  lose  data  without  having  made  a 
backup.  In  some  cases  the  data  lost  can 
be  extensive  and  valuable  and  warrant  an 
effort  in  recovery.  This  is  why  disk  patch¬ 
ing  programs  exist;  many  can  be  found 
in  the  commercial  marketplace  and  the 
public  domain.  Mostly  they  are  useful  if 
files  have  been  inadvertently  erased,  or  a 
sector  develops  an  error  and  becomes  un¬ 
readable  due  to  a  variety  of  possible 
reasons.  Erased  files  can  be  reclaimed  if 
the  disk  is  not  subsequently  written  to 
because  erasing  merely  puts  a  flag  in  the 
directory  entry  for  that  file  which  says 
the  file  is  erased  -  the  data  is  not  literally 
erased.  Therefore  that  flag  can  be  changed 
and  the  file  “un-erased.” 


by  Walter  V.  Murphy 


Walter  V.  Murphy,  Compucations,  212 
Northwood  Avenue,  So.  San  Francisco, 
CA  94080. 

Copyright  ©  1983  by  Walter  V.  Murphy. 
RECLAIM  is  intended  for  non-commercial 
use  only.  Any  commercial  use,  without 
the  author’s  written  permission,  is  pro¬ 
hibited. 


The  problem  is  on  a  more  serious 
level,  however,  if  the  directory  is  more 
extensively  damaged.  In  a  CP/M-based 
system,  storage  space  on  a  disk  is  allocated 
in  blocks.  A  block  is  always  a  multiple  of 
a  sector,  typically  8,  16,  or  32  correspond¬ 
ing  to  IK,  2K,  or  4K  byte  units  of  alloca¬ 
tion  where  a  sector  contains  1 28  bytes. 
These  blocks  are  given  sequential  reference 
numbers  and  these  numbers  are  placed  in 
a  list  in  the  directory  and  associated  with 
a  given  file  name.  The  blocks  assigned  to 
a  file  need  not  be  contiguous  and  it  is 
permitted  for  them  to  be  scattered  in  any 
order  on  the  disk.  These  block  numbers 
are  the  single  most  important  piece  of 
information  the  operating  system  deals 
with  in  maintaining  a  file.  Clearly  if  the 
list  of  block  numbers  is  destroyed  for  an 
individual  file,  the  problem  of  reclama¬ 
tion  is  worsened,  but  if  the  directory  for  an 
entire  disk  is  totally  destroyed,  the  magni¬ 
tude  of  the  problem  can  be  overwhelming, 
particularly  if  the  disk  was  large  and 
almost  full. 

The  program  presented  here  deals 
with  this  kind  of  problem.  The  reclama¬ 
tion  process  cannot  be  fully  automated;  a 
qualified  person  familiar  with  the  types 
of  data  on  the  disk  must  still  inspect  the 
individual  blocks  and  determine  which  to 
save  and  the  order  in  which  to  group 
them.  This  inspection  process  requires 
one  of  the  sector  examination  programs. 
One  which  I  have  used  is  DISK  DOC, 
written  in  C  and  published  in  DDJ  No.  66. 
It  would  make  a  nice  companion  to  RE¬ 
CLAIM.  The  next  step  is  to  retrieve  these 
multiple-sector  blocks  from  the  disk  and 
write  them  into  a  file  on  another  disk. 
RECLAIM  is  almost  indispensible  at  this 
step  in  all  but  the  most  trivial  cases. 

How  RECLAIM  Works 

RECLAIM  is  written  in  Small-C  v.  1 
and  intended  for  use  on  CP/M-compatible 
operating  systems.  It  is  run  while  logged 
into  the  disk  which  is  to  be  reconstructed 
and  it  writes  out  files  containing  a  single 
block  each  onto  a  different  disk.  RE¬ 
CLAIM,  as  it  is  presented  here,  can  only 
be  run  on  systems  compatible  with  CP/M 
2.0  or  better.  This  is  because  RECLAIM 
gets  specific  file  system  information  from 
the  disk  parameter  block.  However,  it 
could  be  modified  to  get  the  file  system 
information  directly  from  a  CP/M  1.4 
system.  RECLAIM  makes  direct  BIOS 
calls  in  order  to  fill  a  block-sized  buffer 
with  all  the  sectors  of  the  requested  block 
and  then  uses  the  file  system  write  com¬ 


mand  to  create  the  file.  When  RECLAIM 
is  run,  it  expects  input  from  STDIN,  the 
standard  input  device,  which  can  be  a  file 
using  Small-C ’s  directed  console  input. 
This  input  is  one  text  line  for  each  block 
to  be  extracted  from  the  disk.  Each  line 
contains  the  track  number,  the  starting 
sector  number  of  the  block,  and  the  file¬ 
name  including  drive  specifier  in  which  to 
write  the  block.  Whenever  a  large  quanti¬ 
ty  of  blocks  is  to  be  reclaimed,  the  list  of 
blocks  should  be  put  into  a  text  file  and 
presented  to  RECLAIM  through  console 
redirection.  The  RECLAIM  program  and 
the  block  list  file  should  never  be  written 
to  the  disk  which  is  to  be  reclaimed; 
instead  they  should  be  accessed  from 
another  disk  by  using  drive  specifiers. 
The  following  example  should  be  very 
clarifying. 

The  block  list  file  “INPUTF1L”  is  a 
text  file  on  A:  containing: 

2,17,a:file.01 

2.33, a:file.02 

2, 49  ,a:  file. 03 

5. 33,  a  Tile. 04 

23,47,a:file.05 

54,1  ,a:file.06 

The  damaged  disk  is  in  drive  B: 
RECLAIM  is  on  drive  A:.  Drive  B:  should 
be  logged  in  as  shown  in  Figure  1  (page 
16).  If  at  any  point  in  the  process  an  error 
occurs,  the  program  trys  to  give  appro¬ 
priate  error  messages  and  then  stops. 

The  overall  recovery  process  can  be 
summarized  as  follows: 

(1)  Use  a  disk  sector  examination 
program  such  as  DISKDOC  to  inspect 
individual  sectors  for  data  characteristics. 
For  example,  it  should  be  very  easy  to 
differentiate  .COM  files  and  text  files  by 
inspection  as  most  disk  sector  examina¬ 
tion  programs  also  show  the  ASCII  test 
equivalent  of  the  bytes  whenever  possible. 

(2)  Decide  which  blocks  will  be  kept 
and  which  are  unimportant.  Make  a  list  of 
blocks  by  track  and  starting  sector  num¬ 
ber.  It  is  not  necessary  to  include  every 
sector  you  wish  to  save,  only  the  starting 
sector  of  every  block.  The  entire  block 
will  be  automatically  retrieved  by  RE¬ 
CLAIM.  The  block  structure  starts  on 
your  disk  at  the  next  sector  immediately 
after  the  directory.  In  a  typical  double¬ 
density  system  with  64  directory  entries, 
the  first  block  is  on  track  2,  sector  17  and 
blocks  are  16  sectors  long.  At  this  time 
make  any  notes  you  can  identifying  the 
contents  of  the  block  so  it  will  be  easier 
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later  to  combine  the  blocks  in  a  way  that 
makes  sense. 

(3)  Using  a  text  editor,  create  a  file 
which  contains  the  list  of  blocks  you  wish 
to  reclaim. 

(4)  Run  the  RECLAIM  program 
while  directing  the  input  text  file  into  it. 

(5)  Examine  any  of  the  files  created 
which  are  text  and  concatenate  them 
appropriately  while  giving  them  meaning¬ 
ful  names.  If  some  files  are  purely  data 
then  you  will  need  information  on  the 
structure  of  that  data  in  order  to  piece  it 
back  together.  In  certain  databases  it  is 
not  unusual  to  find  a  field  which  repre¬ 
sents  the  date,  a  stock  number,  or  line 
item  number.  Usually  there  is  either  a 
fixed  record  length  for  the  database  or  a 
consistent  identifying  pattern  at  the  end 
of  each  record  such  as  a  carriage-return 
line-feed  pair.  Knowing  this  and  using  a 
debugger  such  as  DDT,  you  can  decide 
which  blocks  are  associated  with  each 
other.  Later,  blocks  can  be  concatenated 


—  using  your  text  editor  if  they  are  text, 
or  using  PIP  if  they  are  any  other  kind  of 
data.  Text  data  can  be  verified  by  print¬ 
ing  it  out  and  looking  at  its  appearance. 
Source  code  to  programs  can  be  verified 
by  assembling  or  compiling  them  and 
database  files  can  be  verified  by  using 
them  in  a  test  application. 

I  think  it  is  good  advice  to  not  at¬ 
tempt  to  erase  or  in  any  way  modify  the 
disk  being  reconstructed  until  you  have 
not  only  retrieved  all  the  blocks  of  inter¬ 
est  but  are  also  confident  that  the  order 
in  which  you  have  restored  them  is  cor¬ 
rect.  Good  luck  if  you  attempt  a  large 
recovery  procedure  of  this  sort.  Although 
it  is  tedious  and  time  consuming,  you 
have  nothing  to  lose.  The  best  advice  is, 
as  always,  keep  backups  of  all  important 
data  and  avoid  ever  having  to  reconstruct 
it. 

(Listing  begins  on  page  18) 


B  > 

B >  a:  reclaim  <a  :  inputfil 

COMPUCATIONS  Disk  block  RECLAIMation  utility,  12Aug82. 

This  disk  has  54  sectors  per  track  and  16  sectors  per  block. 

Track:  2,  Starting  Sector:  17,  Filename:  a :  file . 0 1 

Track:  2,  Starting  Sector:  33,  Filename:  a:  file. 02 

Track:  2,  Starting  Sector:  49,  Filename:  a:  file. 03 

Track:  5,  Starting  Sector:  33,  Filename:  a:  file. 04 

Track:  23,  Starting  Sector:  47,  Filename:  a:file.05 

Track:  54,  Starting  Sector:  1,  Filename:  a:  file. 06 

Successful  completion.  Goodbye  from  RECLAIM. 

B  > 

Figure  1. 

RECLAIM  Log  On  for  Drive  B: 
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RECLAIM  (Text  begins  on  page  14) 

/*  RECLAIM. C 

A  utility  for  crashed  disk  data  reel aimation. 

By  Walter  V.  Murphy  <415)  952-4484 
Complications  Computer  Engineering 
212  Nor thwood  Avenue 
South  San  Francisco*  Ca.  94080 

RECLAIM  is  intended  for  non— commercial  use  and 
distributio n . 

This  program  accepts  text  input  lines  from  STDIN  containing 
track*  star-tiro  sector  and  filename  information.  The  indicated 
disk  blocks  are  read  and  assembled  into  files  on  another  disk 
usins  the  specified  names.  Many  lines  of  input  can  be  given  to 
the  program  by  usins  input  redirection. 

The  format  of  the  input  is  as  follows: 

T  rack  *  Sector , Fi 1 ename .ext 

Exarr.pl  e  :  64 ,16.  PROGRAM .  ASM 

65, 48, DATAFILE. AO 1 

When  using  directed  input  the  command  line  looks  like  this: 

RECLAIM  CINPUTFIL 

Where  INF'UTFIL  is  a  text  file  containing  the  input  lines. 

This  allows  generating  a  long  sequence  of  disk  blocks  to 
be  read  using  a  text  editor. 

#/ 

#def  i.  ne  ERROR  -- 1 

ttdefine  TRUE  1 

#de  f  i  r.e  FALSE  O 

#defir.e  NULL  0 

#de f i ne  HOME  30 

#define  ESC  27 

#define  CR  13 

ttdefine  LF  10 

ttdefine  SECLEN  128 

/* 

The  external  declaration  is  here  because  the  Small-C  this  program 
was  intended  for  generates  M80  assembly  language  source  code. 

#/  / 
ex  t  e  r  n  s  t  d  i  r. ,  std  o  u  t ; 

char  *bufr;  /#  block  buffer  */ 

int  track,  /*  for  bios  call  #/ 

sector,  / «•  for  bios  call  */ 

blksiz,  /«■  number  of  sectors  in  a  block  */ 

spt ;  /#  number  of  sectors  per  track  */ 


/•*  These  declarations  would  usually  be  */ 
/ ■#■  in  a  file  called  STEilu.H  #/ 


/*  sector  length  */ 
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char  file  name  C 1 00  3  > 
s  L  1 00 .1 ; 


/*  holds  the  filename.  s  is  the  input  line?  */ 
/*  These  don't  need  to  he  so  long  but  they  */ 
/#  are  Just  for  protection  sake.  */ 


ma i n (  ) 

C  char  *Xi 

-a-addr ; 
i  n  t  i  > 
f  d ; 


/*  x  is  a  working  input  line  pointer.  #/ 

/#  ad dr  is  used  for  giving  the  DMA  to  cp/m.  #/ 
/*  i  is  for  general  use.  */ 

/ fd  is  a  file  descriptor  number.  ■*/ 


i=bdos ( 12»0) ?  /#  get  cp/m  version  number  */ 

if  (  i  /Ox  1 00 )  (  sisnonOi 

printf("\n  This  program  will  not  work  with  MF'/M .  ",1  ) ;  exit(l)5  } 
if  (  (  i '/.Ox  1 00 )  <  0x20)  C  sisnonO; 

printf("\n  This  program  will  not  work  with  less  than  CP/M  2.0."j 

1  )  ; 

exit(l);  3 

if  (  !  s  vsparms  (  )  )  CsignonO?  /*  get  file  system  parameters  */ 
printf("\n  Unknown  system  error.  ".1);  exit(l);  3 

/*  if  memory  is  available-  allocate  it  #/ 
if  (  (  b  u  f  r=  rria  1  1  o  c  (  SECLEN*b  1  k  s  i  )  )  --NULL  )  C  sisnonO  ! 

printf("\n  Not  enough  memory  for  buffer. ".1);  exit(l);  3 

c  1  r  s  c  r  e  e  n  <  )  5 
sign o  n ( ) 5 

printf("\n  This  disk  has  7.d  sectors  per  track  ".spt.2); 

printf("and  V.d  sectors  per  b  1  ock .  \n  "  .  b  1  ks  i  z  .  2 )  ; 


gets ( s ) ; 

while  <#si=NULL)  C 


/*  get  line  from  stdin  #/ 


track=atoi Cx) ;  /*  first  number  in  line  is  track  #/ 

while  (  i  s  d  i  g  i  t  (  #x )  --TRUE  )  ++x  ; 
while  (  i  s  d  i  g  i  t  (  *x )  ===FALSE )  ++x ; 

sector=atoi  (x)  ;  /■»  second  number  in  line  is  sector  -#•/ 

while  (isdigit( #x ) =— TRUE )  ++x ; 
while  (  i  sa 1 pha ( *x ) =-FALSE )  ++x! 

strcpy ( f i 1 ename . x ) ;  /*  the  f i 1 ename  is  last  */ 


/«•  If  you  want  the  second  field  in  your  input  line  to  be  a  track 
relative  block  number  rather  than  sector  number  then  include 
the  following  line: 

sector=  ((sector— 1)*  blksiz)  +1; 

#•/ 

printf("  Track:  %d.  Starting  Sector-:  '/.d,  Filename:  7.s  \  n  " . 

t  r  a c k . sec t o r  »  f i 1 e name . 4 ) ; 
if  (sect  o r  >  s p t )  t 

printf(“  The  sector  requested  is  too  bis.  "»  1)5 
ex i t (  1  )  ; 

3 


(Continued  on  next  page) 
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RECLAIM  (Listing  continued,  text  begins  on  page  14) 


gets(s);  /#  get  line  from  stdin  */ 

i  =*0 ?  a  d  d  r =  bufrl  /#  houj  fill  the  block  buffer  */ 

while  (( dread  ( track?  sector»  addr )  !=  ERROR)  (i  <  blksiz))  { 

addr+=SECLEN;  i++; 

if  ( (sector+*l )>spt)  Csector=l;  track+=l!) 

} 

/*  blksiz  is  number  of  sectors  to  write  */ 
if  <(fd=creat(fil ename ,  0 )  ) ==ERROR ) 

Orintf<"  Unable  to  create  that  file  for  you. 1)5  exit(l);) 
else  i=wr i te ( f d »  buf r  >  b 1 ks i z ) 5 

if  ( ( i ==ERRGR )  !!  (i!=blksiz)) 

Cprintft"  Error  while  writing  that  file. 'SI);  exit(l)?} 
close  <  f d  )  5 

} 

printf<"\7  Successful  completion.  Goodbye  from  RECLAIM. ",  1 ) ; 

/•*  End  of  main  procedure  */ 


s  i  g  n  o  n  (  ) 

£ 

printft"  COMPLICATIONS  Disk  block  RECLAIMat  i  on  utility*  12Aug82.  "  *  1 ) 


/■*  Procedure  to  read  a  sector  using  the  BIOS.  #/ 

/*  Returns  true  or  false  for  success  or  failure.  #/ 


dread ( t  rk»  sec*  addr ) 
i n t  trki sec! 
char  *addr; 

C  b  i  o  s  ( 1 0  *  t  r  k  )  ; 
bios(ll»sec); 
bios(12*addr); 
if  <  b i o s  < 1 3 7 1 ) )  return  0 ; 
return  1 ; 


/*  select  the  track  */ 
/*  select  the  sector  */ 
/*  give  DMA  address  */ 
/#  perform  the  read  */ 

} 


/*  Procedure  to  write  a  sector  using  the  BIOS.  */ 

/#  Returns  true  or  false  for  success  or  failure.  */ 


dwr i te ( trk  5  sec  > addr ) 
i n t  trk»sec! 
char  *addr; 

C  b  i  o  s  (  1 0 »  t  r  k  )  ; 
bios(ll»sec)> 
b  i  o  s  (  1 2  >  a  d  d  r  )  ; 
if  ( b i o  s ( 1 4  7 1 ) )  return  0  5 
return  1 ? 


/*  select  the  track  #/ 
/#  select  the  sector  */ 
/*  give  DMA  address  */ 
/*  perform  the  write  #/ 
) 


/«•  get  system  parameters  from  the  BIOS.  Set  values  for 

sector  count  and  number  of  sectors  in  an  allocation  block 
return  true  if  ok.  ■*/ 
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svsparms ( ) 

C  int  #dph»i; 

char  *dpbj*bsh; 
i=bdos ( 25 .0)1 

if  < ( dph=bios (9. i ) )==0)  return  FALSE; 

d  p  b = d  p  h  C  5  3  ;  /*  set  disk  parameter  block  #/ 

spt=(dpbC13 *0x  1 00 ) +d  p  b  C  0  3 ;  /#  get  #  sectors  per  track  */ 

bsh=dpbC23»  /*  set  block  shift  factor  */ 

blksiz=l;  /*  2**bsh  is  #  sectors  per  block  #/ 

while  (bsh)  Cb 1 ks i z=b 1 ks i z#2i  bsh — ;) 
return  TRUE; 


/#■  carriage  return,  line  feed 
*/ 
n  1  (  ) 

C  t:< d o s  <  2 .  OR ) ;  bdos(2»LF); 

3 

/#  clear  screen 
*/ 

c 1 r screen ( ) 

(  bdos (2, HOME ) ;  bdos ( 2, ESC ) ;  bdos (2, " Y" ) ; 
3 

/#•  Interface  to  call  the  bios. 

*•/ 

b i os ( f un . ars ) 

int  fun.arg; 

C  char  *of  s ; 


#asrn 


■  (  f  u  n  - 

1  )*3; 

POP 

d 

; of f set 

PO  P 

h 

;  ret 

PO  P 

b 

;  arg 

push 

b 

pus  h 

h 

push 

d 

1  hi  d 

1 

; pointer  to 

dad 

d 

;add  offset 

cal  1 
XChS 

g  o  h  1 

; ca 1 1  i nd i re 

mov 

1  7  rk 

mvi 

h.  0 

POP 

b 

;  o  f  s 

push 

b 

mov 

a .  c 

c  pi 

(9-1 3*3 

; se 1 ect  d i sk 

•j  nz 

bios  o  u  t 

xchs 

;  i  f  yes  put 

b  i  o  s  o  u  t : 

ttendasm 

3 

#asm 

g  o  h  1  5  p  c  h  1 

#endasm 


End  Listing 
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Binary  Magic  Numbers 

Some  Applications  and  Algorithms 


This  article  presents  a  set  of  constants 
that  enhances  many  different  kinds 
of  binary  calculations.  These  “magic 
numbers”  can  be  used  to  determine  the 
positions  of  bits  within  words;  to  reverse, 
permute,  and  map  bits  within  words;  to 
compute  sideways  sums  and  parity;  and 
to  convert  Gray  code  values  to  their  bi¬ 
nary  equivalents.  An  understanding  of 
these  numbers  and  their  applications  can 
benefit  the  machine  language  programmer 
and  can  improve  code  generation  in 
compilers.  The  applications  for  these 
constants  will  arise  naturally  in  the  con¬ 
struction  of  algorithms  for  the  solution 
of  each  problem. 

Introduction 

The  field  of  mathematics  has  uncov¬ 
ered  many  “magic  numbers.”  These  are 
numbers  which  have  special  or  unusual 
properties  when  used  in  certain  calcula¬ 
tions.  For  example,  the  magic  number 
142,857  is  the  smallest  “cyclic  number.”1 
Cyclic  numbers  produce  a  result  that  is  a 
cyclic  permutation  of  the  original  num¬ 
ber’s  digits  when  multiplied  by  an  integer 
less  than  or  equal  to  the  number  of  digits 
in  the  original  number: 

1  *  142,857  =  142,857 
2  *  142,857  =  285,714 
3  *  142,857  =  428,571 
4  *  142,857  =  571,428 
5  *  142,857  =  714,285 
6  *  142,857  =  857,142 

Most  magic  numbers  have  little  or  no 
application  apart  from  being  mathemati¬ 
cal  curiosities,  and  no  computer  uses  are 
known  for  them.  Cyclic  numbers  are  no 
exception  to  this;  they  are  elegant  but 
have  no  practical  value.  One  of  the  rea¬ 
sons  for  this  is  that  many  numerical  tricks 
like  cyclic  numbers  rely  on  decimal  (base 
10)  format.  Most  computers  operate  un¬ 
comfortably  at  best  using  base  10  arith¬ 
metic  and  prefer  to  stick  to  binary  (base 
2).  Most  exploration  for  number  “magic” 
has  been  conducted  in  the  decimal  realm, 
so  there  has  been  only  limited  discussion 
of  binary  magic  numbers. 

Binary  magic  numbers  do  exist,  and 
these  numbers  can  be  used  to  significantly 
enhance  certain  computer  operations. 


by  Edwin  E.  Freed 


Edwin  E.  Freed,  Mathematics  Depart¬ 
ment,  Harvey  Mudd  College,  Claremont, 
California. 


This  article  concentrates  on  a  specific  se¬ 
quence  of  binary  magic  numbers.  The 
Nth  number  in  this  sequence  will  consist 
of  an  infinite  sequence  from  right  to  left 
of  2n  l’s,  followed  by  2N  0’s,  followed 
by  2n  l’s,  and  so  on: 

.  .  .  0101010101010101 
.  .  .  00110011001 10011 
.  .  .  0000111100001111 
.  .  .  0000000011111111 


In  practice,  however,  binary  opera¬ 
tions  are  limited  to  a  finite  word  size.  For 
a  word  size  of  8  bits,  there  will  be  three 
numbers: 


B[  1  ]  :=  01010101 
B  [  2  ]  :=  001  10011 
B [ 3 ]  :=  00001  111 

There  will  be  four  B-constants  for  word 
sizes  of  9-16  bits,  five  for  sizes  of  17-32 
bits,  and  so  on.  The  bit  complements  of 
these  binary  values  will  also  prove  to  be 
useful: 


B  [  4  ]  :=  10101010 
B  [  5  ]  :=  11001 100 
B  [  6 )  :=  11110000 


Notation 

All  of  the  example  algorithms  in  this 
article  are  presented  in  Pascal.  The  reader 
is  assumed  to  be  familiar  with  Pascal  and 
with  the  basics  of  boolean  algebra. 

Pascal  does  lack  full-word  logical 
operations  (logical  functions  which  apply 
on  a  bit- for- bit  basis  to  each  bit  in  an 
integer  value)  as  standard  functions,  so 
the  following  special  functions  are  as¬ 
sumed  to  be  implemented: 

lAnd  (X,  Y)  —return  bit-for-bit 
AND  of  X  and  Y. 


IOr  (X,  Y)  —return  bitwise  inclusive 
OR  of  X  and  Y. 

IXor  (X,  Y)  —return  bitwise  exclusive 
OR  of  X  and  Y. 


INot  (X)  —return  bit-for-bit 
complement  of  X. 

LShift  (X,  N)  —return  X  shifted  left 
by  N  bit  positions. 
Zeroes  are  shifted  into 
the  low-order  bits. 

RShift  (X,  N)  —return  X  shifted  right 
by  N  bit  positions. 
Zeroes  are  shifted  into 
high-order  bits. 


Some  of  the  methods  shown  assume 
integer  overflows  will  not  be  detected.  No 
other  extensions  to  Pascal  are  used.  All 
variables  are  explicitly  declared  and  the 
integer  type  is  the  only  type  of  variable 
used.  Some  global  machine-dependent 
constants  are  assumed  to  have  been  de¬ 
clared  outside  the  example  routines.  N  is 
the  number  of  bit  positions  in  an  integer 
value.  V  is  the  base  2  logarithm  of  N 
rounded  to  the  next  highest  integer.  The 
values  B[l]  through  B[2*V]  are  consid¬ 
ered  to  be  global  constants  and  are  fre¬ 
quently  used  in  the  routines.  B  [  1  ]  through 
B[V]  will  be  the  binary  magic  numbers 
defined  above  and  B[V+1]  through 
B[2*V]  will  be  their  bit-for-bit  comple¬ 
ments.  The  constants  S(  1  ]  through  S[N] 
are  a  table  of  the  powers  of  2  within  the 
range  of  the  machine.  S[Q]  will  be  equal 
to  2*3.  The  global  constants  might  be  ini¬ 
tialized  on  a  12-bit  machine  by  th  Pascal 
code  fragment  in  Figure  1 ,  below. 

Most  of  the  algorithms  will  be  more 
useful  if  they  are  recoded  in  a  specific 
machine  language.  No  sophisticated  Pascal 
constructs  like  sets  or  records  are  used,  so 
the  translation  process  should  be  quite 


const 
N  = 


var 


B  : 
S  : 
I  : 


begin 


for 


12;  V  =  4; 


array  [ 1 . - 8 ]  of  integer; 
array  [1..12]  of  integer; 
integer ; 


:=  010101010101  ; 

B 

[2' 

:  =  111  100001  111; 

B 

4  J 

:=  101010101010; 

B 

6 

:  =  00001 1 1 10000; 

B 

[8] 

I  :=  1  to  N  do  S[I]  := 


:=  001 1001 10011; 

: =  00001 1111111; 

:=  110011001100; 

:=  111100000000; 
LShift  (l,  pred  (I)); 


Figure  1 . 
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easy.  The  special  logical  functions  will 
correspond  to  single  instructions  on  most 
machines. 

Some  of  the  algorithms  discussed 
below  will  involve  the  positions  of  bits 
within  words.  Some  consistent  numbering 
scheme  for  these  bits  is  required.  The 
least  significant  bit  of  a  value  is  called 
bit  0  and  numbering  proceeds  to  the  left. 
The  sign  bit  of  the  value  (most  significant 
bit)  will  be  bit  (N-l).  If  the  eight  digit 
positions  in  an  8-bit  word  were  each 
filled  with  their  corresponding  numbers, 
the  result  would  be  76543210.  Note  that 
this  numbering  scheme  can  be  derived 
from  the  constants  B[V+1]  through 
B[2*V]  if  they  are  read  as  binary  values 
from  bottom  to  top  in  each  digit  column. 
This  is  a  very  important  property  of  these 
numbers  that  will  be  used  frequently. 

A  few  of  the  algorithms  assume 
that  negative  values  are  stored  in  two’s- 
complement  form.  This  is  usually  not  a 
problem  —  there  are  not  very  many  one’s- 
complement  or  signed-magnitude  ma¬ 
chines. 

Locating  Bits 

One  commonly  needed  binary  opera¬ 
tion  is  the  ability  to  locate  the  lowest  or 
highest  zero  or  nonzero  bit  in  a  value. 
This  is  often  used  in  operating  systems, 
when  sets  of  boolean  flags  are  grouped 
together  in  a  single  word  and  each  flag 
requires  a  specific  action.  Bit  location 
operations  are  of  particular  interest  in 
scheduling  algorithms,  where  quick  exe¬ 
cution  is  essential. 

Many  large  machines  include  special 
“exotic”  instructions  to  locate  zero  or 
nonzero  bits  in  a  value.  The  DEC- 10  has 
the  JFFO  instruction,  which  is  a  mne¬ 
monic  for  “jump  if  found  first  one.”2 
This  operation  tries  to  find  the  highest 
nonzero  bit  in  a  36 -bit  value  and  option¬ 
ally  branches  if  the  operation  is  successful. 
By  contrast,  the  VAX- 11  instructions  set 
includes  the  FFS  and  FFC  instructions, 
which  are  mnemonics  for  “find  first  set” 
and  “find  first  clear,”  respectively.3  These 
instructions  search  a  field  (an  extracted 
portion  of  a  32-bit  value)  from  the  low¬ 
est  bit  up  for  the  first  zero  or  nonzero 
bit.  Neither  machine  includes  an  explicit 
instruction  for  searching  in  the  opposite 
direction,  although  the  CVTLD  (convert 
long  integer  to  double -precision  floating) 
instruction  on  the  VAX- 11  might  be  used 
for  this.  It  is  also  interesting  to  note  that 
the  instruction  execution  speed  is  bit- 
position  dependent  on  the  DEC- 10  (the 
farther  away  from  an  18-bit  half-word 
boundary,  the  longer  the  instruction 
takes)  and  is  position  independent  on  the 
VAX- 11  (the  same  amount  of  time  is 
taken  for  each  bit  position).4  It  is  vital  to 
be  aware  of  such  speed  dependencies  if 
exotic  instructions  like  these  are  used. 

Smaller  machines  do  not  usually  in¬ 
clude  such  special  instructions.  The  most 


obvious  way  to  perform  this  operation 
is  to  successively  shift  the  value  in  ques¬ 
tion  until  a  bit  in  the  proper  state  is 
found.  The  lowest  bit  can  be  checked 
with  an  AND,  and  the  highest  bit  can  be 
checked  by  watching  for  a  sign  change. 
The  functions  in  Figure  2,  page  28,  illus¬ 
trate  these  methods. 

These  functions  return  a  result  of  -1 
if  no  bit  that  satisfies  the  specified  condi¬ 
tion  can  be  found,  and  the  bit  position  of 
the  selected  bit  otherwise.  Up  to  N  itera¬ 
tions  within  the  functions  may  be  neces¬ 
sary  to  find  the  selected  bit.  However,  it 
is  possible  to  make  use  of  the  B- constants 
and  check  more  than  one  bit  position  with 
each  iteration.  The  functions  in  Figure  3, 
page  28,  perform  complementary  opera¬ 
tions  to  the  functions  shown  above  by 
making  use  of  the  B -constants.  Note  that 
the  LowClearBit  function  operates  on  the 
complement  of  the  input  value  and  not 
on  the  value  itself. 

The  functions  operate  on  multiple 
bit  fields  at  once.  Each  iteration  of  the 
for  loop  isolates  the  desired  bit  to  one- 
half  of  the  remaining  bits  in  a  word.  The 
weighting  of  the  bit  positions  is  used  to 
advantage  in  computing  the  final  position 
by  shifts  and  adds  instead  of  using  a  table 
of  constants  like  S.  The  S-constants 
could  be  used  if  the  shift  operation  is 
difficult  to  implement.  The  assignment  of 
Result  within  the  for  loop  is  superfluous 
during  the  first  iteration  and  may  be 
skipped. 

These  algorithms  take  V  iterations  in 
all  cases.  This  can  be  far  less  than  N  for 
large  word  sizes,  but  the  iterative  loop 
operation  is  more  complex.  The  distribu¬ 
tion  of  bits  in  the  input  values  that  ap¬ 
pear  in  a  given  application  must  also  be 
considered.  The  LowSetBit  function 
presented  in  Figure  2  may  use  an  average 
of  fewer  than  V  iterations  if  nonzero 
low-order  bits  are  prevalent  in  the  input 
values. 

It  is  possible  to  simplify  the  last  two 
functions  if  it  is  known  that  there  is  only 
a  single  nonzero  bit  in  the  value.  It  be¬ 
comes  unnecessary  to  replace  the  input 
value  as  the  algorithm  proceeds  since  the 
desired  bit  is  already  isolated,  so  the 
Temp  and  Ival  variables  are  not  needed. 

It  is  very  easy  to  check  for  a  single 
nonzero  bit  in  a  word.  Given  Value, 
“((Value  O  0)  and  (IAnd  (Value,  pred 
(Value))  =  0))”  will  be  true  if  and  only  if 
there  is  a  single  nonzero  bit  in  Value.5  An 
alternate  test  is  “((Value  <>  0)  and 
(IAnd  (Value,  -Value)  =  Value)).” 

Sideways  Addition 

The  sideways  sum  of  a  number  is  the 
sum  of  all  the  individual  digits  in  the 
number  taken  one  at  a  time.  The  sideways 
sum  will  be  different  depending  on  the 
base  the  number  is  represented  in.  For 
example,  the  sideways  sum  of  the  decimal 
value  12345  is  15,  and  the  sideways  sum 


of  the  binary  value  101 10  is  1 1  (in  binary). 
A  binary  sideways  sum  is  just  the  count 
of  the  l’s  in  the  binary  value. 

Sideways  sums  have  many  interesting 
mathematical  properties  and  applications. 
Decimal  sideways  sums  are  the  basis  for 
an  old  trick  for  determining  divisibility 
by  3  or  9.  If  a  number  is  evenly  divisible 
by  3  then  the  decimal  sideways  sum  will 
also  be  evenly  divisible  by  3.  The  same 
property  holds  true  for  9  as  well.  (The 
decimal  sideways  sum  always  gives  a  value 
with  the  same  remainder  modulo  3  or  9 
as  the  original  value.)  Since  the  sideways 
sum  of  a  number  is  usually  much  smaller 
than  the  number  itself,  it  is  easy  to  check 
divisibility  of  a  large  number  by  iterative¬ 
ly  computing  sideways  sums  until  a  man¬ 
ageably  small  value  is  obtained. 

A  binary  value  can  be  thought  of  as  a 
representation  of  a  set.  Each  digit  corre¬ 
sponds  to  a  single  element  that  may  possi¬ 
bly  be  in  the  set.  A  digit  value  of  0  means 
the  element  is  not  present  and  a  value  of 
1  means  the  element  is  present.  In  this 
scheme  (which  is  used  by  many  program¬ 
ming  languages),  the  binary  sideways  sum 
indicates  the  cardinality  of  a  set  —  it  is  a 
count  of  the  number  of  elements  in  the 
set. 

Some  machines  have  implemented 
the  binary  sideways  sum  as  an  instruction. 
The  CDC  (Control  Data  Corporation) 
6400,  6500,  and  6600  series  processors 
implement  the  “CXi  Xk”  instruction. 
This  instruction  counts  the  number  of 
nonzero  bits  in  register  Xk  and  stores  the 
result  in  register  Xi.  i  and  k  are  single 
octal  digits  and  serve  to  identify  one  of 
the  eight  60-bit  X  registers  available  on 
the  machine.  The  time  used  for  this  oper¬ 
ation  varies  even  within  this  series  of  ma¬ 
chines;  the  6400  and  6500  require  68 
minor  cycles  while  the  6600  needs  only 
eight.  For  comparison  purposes,  an  inte¬ 
ger  addition  takes  six  minor  cycles  on  the 
6400  and  6500  and  three  minor  cycles  on 
the  6600. 6 

The  most  obvious  way  to  compute  a 
binary  sideways  sum  is  to  iteratively  shift 
the  value  right  and  count  the  low-order 
bits  as  shown  in  Figure  4,  at  left. 

This  method  can  take  up  to  N  itera¬ 
tions,  but  it  typically  takes  fewer  than  N 
since  small  values  are  fairly  common. 
There  are  many  possible  variations  on  this 
basic  type  of  function,  including  using 
bits  shifted  out  the  top  of  a  value,  shift¬ 
ing  an  entire  field  out  of  the  value  and 
looking  up  its  sideways  sum  in  an  auxili¬ 
ary  table,  and  using  floating-point  nor¬ 
malization  hardware  if  it  is  available. 

The  test  for  a  single  nonzero  bit  pre¬ 
sented  above  may  also  be  adapted  to  pro¬ 
duce  a  sideways  summation  algorithm 
(see  Figure  5,  at  left).  The  number  of 
iterations  for  this  method  is  equal  to  the 
final  sideways  sum  result.  The  average 
number  of  iterations  would  be  N/2  if 
a  random  value  (each  bit  has  an  equal 
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function  LowSetBit  (Value  :  integer)  :  integer; 

var 

Temp,  Result  :  integer; 

begin 

if  Value  =  0  then  LowSetBit  ;=  -1 
else  begin 

Temp  :=  Value; 

Result  :=  0; 

while  not  odd  (Temp)  do  begin 
Temp  :=  RShift  (Temp,  l); 

Result  :=  succ  (Result); 
end; 

LowSetBit  :=  Result; 
end; 
end ; 

function  HiClearBit  (Value  :  integer)  :  integer; 

var 

Temp,  Result  :  integer; 

begin 

Temp  :=  Value; 

Result  :=  pred  (N); 
while  Temp  <  0  do  begin 
Temp  :=  LShift  (Temp,  l); 

Result  :=  pred  (Result); 
end ; 

HiClearBit  :=  Result; 
end ; 

Figure  2. 


function  LowClearBit  (Value  :  integer)  :  integer; 

var 

Temp,  Result,  Ival,  I  :  integer; 

begin 

if  Value  =  -1  then  LowClearBit  :=  -1 

else  begin 

Ival  :=  IHot  (Value); 

Result  :=  0; 

for  I  :=  V  dovnto  1  do  begin 
Result  :=  LShift  (Result,  l); 

Temp  :=  IAnd  (ival,  B [ I ] ) ; 
if  Temp  =  0  then  Result  :=  succ  (Result) 
else  Ival  :=  Temp; 
end ; 

LowClearBit  :=  Result; 
end ; 
end ; 


function  HiSetBit  (Value  :  integer) 

var 

Temp,  Result,  Ival,  I  :  integer; 
begin 

if  Value  =  0  then  HiSetBit  :=  -1 
else  begin 

Ival  :=  Value; 

Result  ;=  0; 

for  I  :=  V  dovnto  1  do  begin 
Result  ;=  LShift  (Result,  1); 
Temp  :=  IAnd  (Ival,  B[V+l]); 
if  Temp  <>  0  then  begin 
Result  :=  succ  (Result); 
Ival  :=  Temp; 
end ; 
end ; 

HiSetBit  :=  Result; 
end ; 

end;  ~ 

Figure  3. 


integer ; 


chance  of  being  0  or  1)  is  input. 

It  is  possible,  however,  to  operate  on 
multiple  fields  within  a  value  simultane¬ 
ously,  first  adding  adjacent  bits,  then  bit 
pairs,  and  so  on.  The  coding  of  this  meth¬ 
od  is  set  forth  in  Figure  6,  at  left.  This 
method  uses  only  the  uncomplemented 
B-constants  and  takes  V  iterations  in  all 
cases.  There  is  only  a  slight  increase  in  the 
number  of  operations  required  in  the 
loop  over  the  first  SideSum  function. 
This  method  is  preferred  when  a  large 
number  of  l’s  are  expected  in  the  input 
value. 

Parity 

A  slight  variation  on  sideways  addi¬ 
tion  is  to  just  record  whether  or  not  the 
sum  of  the  digits  is  even  or  odd.  This  re¬ 
sult  is  called  the  parity  of  a  number  and 
applications  for  it  frequently  arise  in 
error  correction  techniques. 

Parity  is  usually  thought  of  as  the 
exclusive-OR  of  all  the  binary  digits  in 
a  value  —  thus  a  0  indicates  even  parity 
and  a  1  indicates  odd  parity.  Many  micro¬ 
computers  include  hardware  to  compute 
parity  bits  easily,  but  many  larger  ma¬ 
chines  do  not  have  such  facilities.  The 
simplest  way  to  compute  parity,  illustrated 
in  Figure  7,  at  left,  is  analogous  to  the 
first  method  for  sideways  sum  computa¬ 
tion  involving  repetitive  shifts  and  tests. 

As  before,  this  operation  can  take  up 
to  N  iterations  but  typically  requires 
somewhat  fewer.  The  method  can  be  al¬ 
tered  to  take  advantage  of  link  bits  or 
floating-point  normalization  instructions 
(which  typically  shift  the  uppermost 
nonzero  bit  to  the  highest  bit  position 
automatically).  For  example,  the  8087 
numeric  data  processor  can  be  used  in 
this  fashion  by  reading  an  integer  value 
into  the  unit  and  subsequently  writing 
the  value  out  in  floating-point  form.7  The 
mantissa  of  the  result  will  then  be  the  orig¬ 
inal  integer  shifted  left  so  that  the  highest 
nonzero  bit  is  at  the  top  of  the  field,  and 
the  exponent  is  an  indication  of  the  num¬ 
ber  of  shifts  that  were  needed.  Care  must 
be  taken  to  intercept  negative  values  and 
to  use  a  floating-point  format  capable  of 
holding  an  entire  integer  in  its  mantissa 
without  loss  of  accuracy.  The  8087  is 
slightly  cumbersome  to  use  in  this  fashion 
as  it  requires  reading  and  writing  the  val¬ 
ues  into  memory  instead  of  performing  the 
operation  entirely  in  registers.  Machines 
with  simple  conversion  instructions  are 
actually  more  versatile  in  this  case. 

The  second  method  presented  for 
sideways  addition  can  also  be  adapted  to 
compute  parity.  This  algorithm  is  easily 
derived  from  the  SideSum  function  and 
will  not  be  presented  here. 

Figure  8,  at  left,  shows  how  the  third 
method  for  sideways  addition  can  be 
adapted  into  a  parity  function  with  consid¬ 
erable  ease.  This  algorithm  always  takes 
V  iterations.  The  B-constants  are  not  re- 


28 

178 


Dr.  Dobb’s  Journal,  Number  78,  April  1983 


quired  since  exclusive-OR  operations  do 
not  generate  carries  and  masking  is  not 
necessary. 

One  peculiarity  that  must  occasional¬ 
ly  be  dealt  with  is  machines  that  do  not 
possess  exclusive-OR  hardware.  Of  course, 
the  exclusive-OR  may  be  coded  in  terms 
of  other  logical  operations  (see  Figure  9, 
at  left).  This  is  a  very  costly  operation.  It 
may  be  more  practical  to  compute  the  full 
sideways  sum  and  extract  the  lowest  bit 
rather  than  using  this  cumbersome 
function. 

The  third  sideways  sum  technique 
may  alternately  be  adapted  to  provide  the 
parity  of  a  value  using  only  ANDs,  shifts, 
and  normal  addition.  This  is  accomplished 
by  noting  that  an  exclusive-OR  is  essen¬ 
tially  an  addition  with  no  carry,  so  all 
that  must  be  done  is  to  prevent  additive 
carries  from  crossing  from  one  field  of 
the  number  to  the  next,  as  in  Figure  10, 
at  left.  This  technique  is  interesting 
in  that  it  requires  only  one  of  the  binary 
magic  numbers.  (V-l)  iterations  are  re¬ 
quired,  but  some  preliminary  calculations 
of  greater  complexity  than  the  iterative 
one  must  be  performed. 

Another  peculiarity  of  some  machines 
is  the  lack  of  an  AND  instruction.  Such 
machines,  notably  the  LSI- 11,  PDP-11, 
and  VAX-11,  have  a  bit  test  instruction 
(BIT)  that  performs  an  AND  but  does 
not  store  the  result.  These  machines  also 
have  a  bit  clear  instruction  (BIC),  which 
corresponds  to  an  “AND-NOT”  opera¬ 
tion.3  This  does  not  present  a  problem 
with  any  of  the  algorithms  shown  in  this 
article.  Most  uses  of  IAnd  involve  a  con¬ 
stant.  The  constant  is  just  complemented 
and  then  the  BIC  operation  can  be  used. 
One  exception  to  this  is  the  IXor  func¬ 
tion,  which  can  be  recoded  more  simply 
using  the  statement  “IXor  :=  IOr  (BIC 
(X,  Y),  BIC  (Y,  X)).”  The  only  other  ex¬ 
ceptions  are  the  tests  for  a  single  nonzero 
bit.  The  first  test  does  not  require  the 
storage  of  the  result,  so  a  BIT  instruction 
could  be  used  or  an  INot  can  be  inserted. 
The  second  test  can  be  expressed  as 
“((Value  <>  0)  and  (BIC  (Value,  pred 
(Value))  =  Value)).” 

Weighted  Sideways  Addition 

Sometimes  it  is  necessary  to  perform 
sideways  addition  with  each  digit  weighted 
differently.  This  requires  multiplying 
each  digit  by  a  fixed  constant  before  sum¬ 
mation  is  done.  The  way  numbers  are 
normally  interpreted  is  merely  a  special 
case  of  this  operation;  each  digit  of  a 
number  is  weighted  by  successive  powers 
of  the  base  of  the  number  system.  Thus 
numbers  themselves  can  be  thought  of  as 
just  collections  of  digits  where  a  particu¬ 
lar  type  of  weighted  sideways  addition  is 
used  to  compute  their  value.  The  conven¬ 
tional  sideways  sum  is  another  special 
case  —  each  digit  has  unary  weight. 


function  SideSum  (Value  :  integer)  :  integer; 

var 

Temp,  Result  :  integer; 

begin 

Temp  :=  Value; 

Result  :=  0; 

while  Temp  <>  0  do  begin 

Result  :=  Result  +  IAnd  (Temp,  1); 

Temp  :=  RShift  (Temp,  1); 

end ; 

SideSum  :=  Result; 
end ; 

Figure  4. 


function  SideSum  (Value  :  integer)  :  integer; 

var 

Temp,  Result  :  integer; 
begin 

Temp  :=  Value; 

Result  :=  0; 

while  Temp  <>  0  do  begin 
Result  :=  succ  (Result); 

Temp  :=  IAnd  (Temp,  pred  (Temp)); 
end ; 

SideSum  :=  Result; 
end ; 

Figure  5. 


function  SideSum  (Value  :  integer) 

:  integer; 

var 

Result,  I  :  integer; 
begin 

Result  :=  Value; 
for  I  : =  1  to  V  do 

Result  :=  IAnd  (RShift  (Result, 

s[i]),  B[ I ] )  + 

IAnd  (Result,  B[l]); 

Sidesum  :=  Result; 
end ; 

Figure  6. 

function  Parity  (Value  :  integer)  :  integer; 

var 

Temp  :  integer; 
begin 

Temp  :=  Value; 

Result  :=  0; 

while  Temp  <>  0  do  begin 

Result  :=  IXor  (Temp,  Result); 

Temp  :=  RShift  (Temp,  l); 
end ; 

Parity  :=  IAnd  (Result,  l); 
end ; 

Figure  7. 
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function  Parity  (Value  :  integer)  :  integer; 

var 


Result,  I  :  integer; 

begin 

Result  :=  Value; 
for  I  :=  1  to  V  do 

Result  :=  IXor  (Result,  RShift  (Result,  S [ I ] ) ) ; 
Parity  :=  IAnd  (Result,  l); 

end;  Figure  8. 


j  function  IXor  (X,  Y  :  integer)  :  integer; 
begin 

IXor  :=  IAnd  (INot  (IAnd  (X,  Y)),  IOr  (X,  Y)); 

end ; 

Figure  9. 


function  Parity  (Value  :  integer)  :  integer; 
var 

Result,  I  :  integer; 
begin 

Result  :=  IAnd  (IAnd  (RShift  (Value,  l),  B[ 1 ] )  + 
IAnd  (Value,  B[l ] ) ,  B[l ] ) ; 
for  I  :=  2  to  V  do 

Result  :=  IAnd  (RShift  (Result,  S [ I ] ) 

+  Result ,  B[ 1 J ) ; 

Parity  :=  IAnd  (Result,  1); 
end ; 

Figure  10. 


function 

var 

WeightedSum  (Value  : 

integer)  :  integer; 

Temp , 

Result,  I  :  integer; 

begin 

Result 

:=  0; 

Temp  : 

=  Value; 

I  :=  1 
while 

y 

Temp  <>  0  do  begin 

: =  Result  +  C[ I ] ; 

if  odd  (Temp)  then  Result 

Temp 

:  =  RShift  (Temp ,  1  ) ; 

I  :  = 

succ  (I); 

end ; 

,  WeightedSum  :=  Result; 

end; 

Figure  1 1. 

integer)  :  integer; 


function  WeightedSum  (Value 

var 

Temp,  Result,  I  :  integer; 

begin 

Result  :=  0; 

for  I  :=  1  to  K  do  begin 

SideSum  (IAnd  (Value,  D[l]),  Temp); 
Result  :=  LShift  (Result,  1)  +  Temp; 
end ; 

WeightedSum  :=  Result; 
end; 

Figure  12. 


Weighted  sideways  sums  can  be  used 
to  generate  arbitrary  mappings  and  per¬ 
mutations  of  bits  within  words.  A  permu¬ 
tation  is  a  rearrangement  of  the  bits 
within  a  word  where  no  bits  are  lost,  and 
a  mapping  is  a  more  general  operation  in 
that  a  bit  may  be  placed  in  more  than  one 
position  in  the  final  result  and  certain  bits 
may  be  lost.  It  is  trivial  to  construct  a  set 
of  weights  for  a  sideways  sum  that  will 
accomplish  any  mapping  or  permutation 
—  each  bit’s  weight  is  a  mask  containing 
l’s  in  the  bit  positions  the  bit  is  to  be 
mapped  into. 

The  additive  properties  of  a  weighted 
sideways  sum  can  be  used  in  a  more  gen¬ 
eral  sense,  however.  Consider  a  binary 
value  as  a  representation  of  a  set,  as  it 
has  been  discussed  earlier.  Each  potential 
element  of  the  set  might  be  said  to  have 
certain  properties.  Different  elements  will 
have  different  properties.  There  can  be 
many  properties  associated  with  each 
member.  Take  the  set  of  fruits  [LIME, 
LEMON,  ORANGE] .  One  property 
might  be  color  —  [GREEN,  YELLOW, 
ORANGE] .  Another  might  be  cost  —  [41 
cents,  35  cents,  52  cents],  A  third  might 
be  ordinal  position  -  [first,  second,  third] . 

Some  properties  are  not  additive 
(like  color)  and  others  (position  or  cost) 
are.  It  may  not  make  sense  to  total  the 
positions  of  the  elements  of  a  set,  but  a 
property  like  cost  might  be  useful  to  sum 
over  an  entire  set.  In  the  binary  represen¬ 
tation  of  a  set,  the  costs  could  be  thought 
of  as  weights  and  the  resultant  sideways 
sum  as  the  cost  of  the  entire  set. 

The  straightforward  way  to  compute 
a  weighted  sideways  sum  is  to  maintain  a 
table  of  constant  weights  and  to  iteratively 
shift  the  input  value.  For  the  function 
shown  in  Figure  11,  page  33,  a  table  of 
constant  weights  C[l]  through  C[N] 
applying  to  each  respective  bit  position  is 
assumed  to  be  defined. 

This  routine  takes  a  maximum  of  N 
iterations,  which  is  to  be  expected.  There 
is  no  clear  way  to  write  a  more  efficient 
routine  using  the  B-constants.  It  is  neces¬ 
sary  to  examine  the  constant  weights  in  C 
for  certain  bit  patterns.  Consider  the  fol¬ 
lowing  ascending  sequence  for  an  8 -bit 


machine: 

cm 

:=  0001 

C  [  5  ]  :=  0101 

C  [  2  ] 

:=  0010 

C[6]  :=0110 

C  [  3  ] 

:=  0011 

C  [  7  ]  —0111 

C  [  4  ] 

:=  0100 

C[8]  :=  1000 

A  new  set  of  weights  can  be  derived  by 
reading  the  columns  of  the  C  array.  This 
is  equivalent  to  constructing  an  8  x  8 
matrix  with  the  rows  of  C  and  taking  the 
reversed  rows  of  the  transpose  of  this 
matrix.  This  will  create  a  new  set  of  con¬ 
stants  D[  1  ]  through  D[K] .  K  =  4  for  the 
example  C-constants  given  above,  since 
D[5]  through  D[8]  will  all  be  zero.  In 
this  example,  the  D- constants  are  actual¬ 
ly  shifted  versions  of  the  B-constants. 
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function  ReverseBits  (Value  :  integer)  :  integer; 

var 

Temp,  Result,  I  :  integer; 
begin 

Temp  :=  Value; 

for  I  :=  1  to  N  do  begin 

Result  :=  LShift  (Result,  1)  +  IAnd  (Temp,  1); 
Temp  :=  RShift  (Temp,  1); 
end; 

ReverseBits  :=  Result; 

end;  c" 

Figure  13. 


function  ReverseBits  (Value  :  integer)  :  integer; 

var 

Result,  I  :  integer; 
begin 

Result  :=  Value; 
for  I  :=  1  to  V  do 

Result  :=  IAnd  (LShift  (Result,  S[ I  ] ) ,  B[V+l])  + 
IAnd  (RShift  (Result,  S[ I  ] ) ,  B[l]); 

ReverseBits  :=  Result; 
end ; 

Figure  14. 


function  GrayToBinary  (Value 

:  integer)  :  integer; 

var 

Temp,  Result  :  integer; 
begin 

Result  :=  0; 

Temp  :=  Value; 

while  Temp  <>  0  do  begin 

Temp) ; 

Result  :=  IXor  (Result, 

Temp  :=  RShift  (Temp,  l) 
end ; 

GrayToBinary  :=  Result; 

1 

end ; 

Figure 

15. 

function  GrayToBinary  (Value  :  integer)  :  integer; 

var 

Result,  I  :  integer; 

begin 

Result  :=  Value; 
for  I  : =  1  to  V  do 

Result  :=  IXor  (Result,  RShift  (IAnd  (Result, 

T [ I  ] )  ,  S[I  ] )  * 

(pred  (S[succ  (S[l])])); 

GrayToBinary  :=  Result; 
end ; 


Figure  16. 


Now  the  D-constants  can  be  used  to 
reduce  the  weighted  summation  to  a  series 
of  unweighted  sideways  sums.  Each  un¬ 
weighted  sum  builds  a  single  quantity  of 
constant  weight  for  the  final  result,  as 
illustrated  in  Figure  12,  below. 

This  method  is  by  no  means  faster 
than  the  conventional  version  of  Weighted- 
Sum  for  a  general  set  of  weights.  However, 
certain  special  cases  (such  as  the  example 
weights  given  in  Figure  12)  will  introduce 
a  multitude  of  simplifying  reductions  if 
the  SideSum  function  is  coded  inline, 
particularly  if  the  D-constants  bear  some 
resemblance  to  the  B- constants.  The 
reduction  of  the  example  is  left  as  an 
exercise  to  the  reader.  Which  Weighted- 
Sum  method  takes  fewer  operations? 

Bit  Reversal 

Another  interesting  operation  to 
study  is  that  of  reversing  all  the  bits  in  a 
word.  Bit  0  will  become  bit  (N-l),  bit  1 
will  become  bit  (N-2),  bit  2  will  become 
bit  (N-3),  and  so  on.  This  is  actually  a 
special  case  of  the  weighted  sideways  sum 
operation,  since  it  is  nothing  more  than  a 
permutation  of  the  bit  positions  in  a  val¬ 
ue.  One  application  for  bit  reversal  has 
already  been  encountered  in  the  construc¬ 
tion  of  the  D  array  from  the  C- constants 
for  the  second  method  of  weighted  side¬ 
ways  addition. 

Bit  reversal  may  easily  be  imple¬ 
mented  by  a  series  of  shifts  (see  Figure 
13,  below).  N  iterations  are  always  re¬ 
quired  for  this  function. 

This  function  may  be  modified  to 
reverse  the  bits  in  a  quantity  (2*N)  bits 
long.  The  high-order  part  of  the  input 
quantity  is  passed  in  Result,  and  all  that 
is  necessary  is  to  modify  the  function  to 
copy  the  sign  bit  of  Result  to  the  sign  bit 
of  Temp  on  each  iteration.  The  final 
value  will  be  contained  in  Temp  and  Re¬ 
sult.  No  additional  iterations  are  needed. 

Many  small  computers  have  an  addi¬ 
tional  bit  which  is  attached  to  the  high- 
order  end  of  the  register  used  for  shift 
operations.  This  bit  is  usually  called  the 
link  or  carry  flag.  This  bit  can  be  a  nui¬ 
sance  when  performing  some  circular  ro¬ 
tate  operations  since  it  acts  as  an  extra 
bit  position  between  the  least  significant 
bit  and  the  sign  bit.  Nevertheless,  a  carry 
flag  can  be  used  to  advantage  in  bit-reversal 
routines.  For  example,  the  Motorola 
6800  can  be  used  for  bit  reversal  of  a 
16-bit  quantity  if  the  high-order  8  bits  of 
the  input  value  are  placed  in  accumulator 
A,  the  low-order  8  bits  of  the  input  value 
are  placed  in  accumulator  B,  the  following 
two  instructions  are  repeated  eight  times: 

ROL  A 

ROR  B 

and  finally  a  single  “ROL  A”  instruction 
is  executed.  The  result  will  be  in  the  accu¬ 
mulators  in  the  same  configuration  as  the 
input  value.  The  H,  I,  and  C  flags  will  be 
unaffected  and  the  N,  Z,  and  V  flags  will 
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be  set  according  to  the  high -order  8  bits 
of  the  result. 

It  is  possible  to  use  the  B- constants 
to  minimize  the  number  of  iterations  re¬ 
quired  as  in  Figure  14,  at  left.  This 
method  is  restricted  to  machines  where  N 
is  a  power  of  2.  This  will  not  be  a  prob¬ 
lem  on  most  processors  since  word  lengths 
of  8,  16,  and  32  bits  are  the  most  com¬ 
mon.  There  are  some  processors,  however, 
where  this  method  cannot  be  imple¬ 
mented,  like  the  PDP-8  and  Intersil  6100 
(12-bit),  the  DEC-10  (36-bit),  and  most 
CDC  machines  (60-bit).  This  method  re¬ 
quires  only  V  iterations  in  all  cases.  It 
should  be  avoided  on  machines  which 
have  difficulty  in  shifting  a  quantity  by 
more  than  one  bit  position  at  once,  and 
on  machines  whose  word  length  is  not 
a  power  of  2. 

Gray  Codes 

Gray  codes  are  essentially  an  alter¬ 
nate  set  of  counting  numbers  that  have 
different  rules  than  most  conventional 
number  systems.  When  Gray  code  num¬ 
bers  are  placed  in  counting  order,  any 
adjacent  pair  of  numbers  will  differ  in  at 
most  one  digit  position,  and  the  absolute 
value  of  the  difference  in  that  digit  posi¬ 
tion  will  always  be  one. 

There  are  an  infinite  number  of  Gray 
codes,  and  Gray  codes  exist  for  every  nu¬ 
meric  base.  The  simplest  Gray  code  of  all 
is  the  binary  reflected  Gray  code,  which 
will  be  the  code  under  discussion  here. 
The  binary  reflected  Gray  code  is  used 
more  often  than  any  other  Gray  code. 

Gray  codes  have  many  applications 
such  as  error  correction  in  pulse-code 
modulated  systems.  There  are  several 
places  in  recreational  mathematics  where 
Gray  codes  turn  up;  the  disk  motion 
of  the  Towers  of  Hanoi  problem  is  an 
example.8 

It  is  easy  to  convert  an  ordinary 
binary  number  into  its  binary  reflected 
Gray  code  equivalent.  If  Value  is  the 
binary  number,  “IXor  (Value,  RShift 
(Value,  1))”  will  be  the  Gray  code 
equivalent  for  Value.  The  conversion  of  a 
Gray  code  number  to  its  binary  equiva¬ 
lent  is  not  so  easy.  Each  bit  of  the  original 
binary  number  may  be  recreated  by 
taking  the  exclusive-OR  of  the  corre¬ 
sponding  bit  in  the  Gray  code  with  all  the 
bits  to  its  left  (higher-order  bits  including 
the  sign  bit).  For  example,  a  binary  value 
of  0111  would  be  converted  to  0100  in 
Gray  code. 

The  conversion  of  a  Gray  code  value 
into  its  original  binary  form  may  be  ac¬ 
complished  by  the  function  in  Figure  15, 
page  34.  The  function  requires  at  most 
N  iterations  to  complete  the  operation. 

The  final  value  created  can  be  repre¬ 
sented  in  tabular  form  as  an  “addition 
problem,”  where  exclusive-OR  is  used 
instead  of  normal  addition.  If  each  bit 
position  in  Value  is  labeled  with  a  letter 


“a”  through  “n”  (assuming  that  N=8 
and  “a”  is  the  label  for  the  highest  bit), 
the  problem  can  be  seen  as: 

abcdefgh 

abcdefg 

abcdef 

abcde 

abed 

abc 

ab 

a 

Result 

In  order  to  solve  the  problem  in  V 
iterations,  it  is  useful  to  first  define  the 
set  of  augmented  constants  T[  1  ]  through 
T[V]  by  the  relationship  “T[Q]  :=  I  And 
(LShift  (B [Q] ,  1),  LShift  (B[Q] ,  S[Q] )).” 
The  T-constants  are  shown  here  for  N  = 
16: 

T[  1  ]  :=  1010101010101010 
T[2]  :=  0100010001000100 
T[3]  :=  0001000000010000 
T[4]  :=  0000000100000000 

The  Nth  T-constant  is  formed  by  repeat¬ 
ing  a  pattern  from  right  to  left  of  (2N_1 ) 
Os,  followed  by  a  single  1,  followed  by 
(2N1  - 1 )  Os. 

The  method  used  with  the  T-constants 
is  vaguely  similar  to  the  “divide  and 
conquer”  method  of  Ercegovac.9, 10  Each 
iteration  builds  several  different  fields  of 
the  final  result.  Multiplication  is  used  in 
the  loop  —  this  method  should  be  avoided 
on  machines  which  do  not  have  integer 
multiplication  hardware.  The  multiply 
operation  is  used  to  shift  single- bit  fields 
into  multiple  positions  in  the  word  (see 
Figure  16,  page  35). 

The  pattern  generated  by  this  func¬ 
tion  is  quite  interesting.  After  the  first 
iteration,  the  value  in  Result  is  (using  the 
same  “addition  problem”  notation  as 
above  and  assuming  N  =  8): 

abcdefgh 
a  c  e  h 
Result 

After  the  second  iteration,  the  pattern  is: 

abcdefgh 
abc  efg 
ab  ef 
a  e 
Result 

On  the  third  and  final  iteration,  the 
binary  equivalent  is  obtained. 

Generation  of  Constants 

It  may  be  necessary  in  some  pro¬ 
gramming  environments  to  create  the 
B-constants  dynamically  instead  of  just 
reading  them  from  a  table.  The  B-constants 
are  easily  generated  using  the  S-constants 
(which  are  in  turn  quite  easy  to  create 
using  a  single  LShift).  See  Figure  17,  at 
right. 

The  dynamic  generation  of  the  B- 
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constants  may  be  “blended”  with  the 
inner  loop  of  most  of  the  algorithms 
given  in  this  article.  Each  iteration  of  the 
loop  then  generates  the  constant  it  re¬ 
quires  using  a  temporary  variable  that  is 
initially  set  to  -1.  Unfortunately,  it  does 
not  appear  to  be  possible  to  perform  this 
operation  in  the  reverse  order,  that  is, 
derive  B[Q  +  1]  from  B[Q] .  This  makes 
it  difficult  to  add  the  code  for  dynamic 
generation  of  the  B-constants  to  the 
inner  loop  of  the  SideSum  function.  Al¬ 
though  the  ReverseBits  function  loop  is 
written  in  ascending  order,  it  may  operate 
in  either  direction,  so  it  is  possible  to 
generate  the  B-constants  as  the  loop 
proceeds. 

The  T-constants  used  in  the  GrayTo- 
Binary  algorithm  may  be  generated  from 
the  B-constants  by  using  their  defining 
relationship.  Alternately,  a  similar  itera¬ 
tive  process  can  be  used,  which  also  pro¬ 
ceeds  in  the  wrong  direction  to  make  it 
useful  within  the  inner  loop  of  the  Gray- 
ToBinary  function  (see  Figure  18,  page 
36).  The  assignment  of  Temp  in  the  last 
iteration  of  the  loop  is  not  needed  and 
always  sets  Temp  to  -1. 

Advanced  Applications 

More  sophisticated  applications  for 
the  B-constants  exist.  They  can  be  used 
to  transpose  bit  matrices11, 12  and  there 
are  even  applications  for  these  constants 
in  certain  error  correcting  codes.  These 
applications  are  beyond  the  scope  of  this 
article,  and  might  be  the  subject  of  a 
future  one. 

Conclusion 

This  article  has  covered  many  appli¬ 
cations  for  this  particular  set  of  binary 
constants.  The  behavior  of  all  these 
algorithms  seems  to  have  a  lot  of  things 
in  common  —  the  normal  and  obvious 
method  for  performing  the  operation 
typically  takes  up  to  N  iterations,  where 
N  is  the  word  size  of  the  machine,  and 
the  method  using  the  B-constants  takes  V 
operations,  where  V  is  the  base  2  loga¬ 
rithm  of  N  rounded  up  to  the  nearest 
integer.  For  large  word  sizes  (or  when 
operating  on  multiword  values  with  a 
smaller  machine),  these  algorithms  repre¬ 
sent  a  considerable  savings  in  execution 
time.  Judicious  use  of  these  techniques 
may  improve  many  machine-language 
programs. 
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An  8080  Fig-Forth 
Directory  and  File  System 


This  article  describes  a  Forth  program 
which  overlays  a  directory  and  file 
system  on  the  version  of  Fig-Forth 
which  has  been  adapted  to  the  North  Star 
disk  system  by  Interactive  Computer  Sys¬ 
tems,  Inc.,  6403  Demarco  Road,  Tampa, 
Florida  33614.  The  program  requires 
only  one  CODE  word  linkage  to  the 
North  Star  DOS  to  implement  a  dozen 
useful  file  commands.  Except  for  this  one 
disk-system -peculiar  word,  the  entire  file 
overlay  is  written  in  high-level  Forth; 
hence  the  end  product  is  highly  portable. 

The  article  commences  with  a  com¬ 
mands  summary  in  Fig-glossary  style. 
This  is  followed  by  a  short  discussion  of 
the  author’s  rationale  for  the  approach 
used  and  a  description  of  the  North  Star 
disk  and  directory  formats.  The  article 
concludes  with  a  few  explanatory  notes 
as  an  aid  in  deciphering  the  appended 
listing. 

Summary  of  Commands 

All  commands  that  prompt  for  input 
can  be  aborted  after  the  prompt  occurs 
by  typing  a  ctrl-c.  Input  errors  which  are 
detected  by  the  operator,  as  opposed  to 
the  command  itself,  may  be  corrected  by 
typing  a  space  and  re-entering  the  correct 
input  after  the  prompting  error  message. 
File  names  and  disk  names  may  be  from 
one  to  eight  of  any  printing  ASCII  char¬ 
acters  from  !  to  Z  inclusive  (33  hex  to  5A 
hex  inclusive).  Note  that  this  differs  from 
the  North  Star  format,  which  requires 
alpha  and  numbers  only.  The  validity  of 
the  range  of  drive  numbers  (1-3)  is 
checked  in  all  commands  where  drive 
number  is  an  input. 

The  following  is  a  summary  of  the 
commands  in  Fig-glossary  style: 

CD  DR  #  1  DR  #2  .  .  . 

Copies  diskette  on  drive  DR#1  to  disk¬ 
ette  on  drive  DR#2. 

CF  DR#1  DR #2  .  .  . 

Copies  a  named  file  on  drive  DR#1  to  a 
named  file  on  DR #2.  The  names  of  the 
files  are  prompted.  The  file  on  drive 
DR #2  does  not  have  to  pre-exist;  its 
directory  entry  will  be  created.  If  it  does 
pre-exist,  the  file  transfer  will  occur  only 
if  the  file  is  sufficiently  large.  If  the  file  is 
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created,  it  will  be  checked  for  possible 
disk  overflow.  If  overflow  would  occur, 
the  command  aborts. 

CLR-SCR  SCR  #1  SCR  #2  .  .  . 

Clears  a  block  of  screens  from  SCR#1  to 
SCR  #2. 

CRF  DR#1  .  .  . 

Creates  a  named  file  on  drive  DR#1. 
Prompts  for  file  name,  screen  start,  screen 
stop,  file  type.  Will  create  a  directory  en¬ 
try  for  all  file  types  except  a  Forth  data 
file  (type  5).  Forth  source  program  files 
should  be  designated  as  type  4.  Type  1 
files  (object  code)  will  request  a  hex  load- 
and-go  address.  In  keeping  with  the  gener¬ 
al  permissiveness  of  Forth,  no  check  is 
made  for  the  validity  of  the  screen  num¬ 
bers.  Checks  for  existing  file  of  same 
name  and  aborts  if  found.  Existing  file 
entry  may  be  changed  by  ED  command 
followed  by  CRF  command.  Does  not 
check  for  potential  disk  overflow  and 
assumption  is  that  all  screens  of  named 
file  are  contiguous  on  the  same  disk. 

CSCR  SCR  #  1  SCR  #2  SCR  #3 .  .  . 
Copies  block  of  screens  SCR#1  to 
SCR  #2  inclusive  to  block  of  screens 
starting  at  SCR  #3. 

CSEC  SEC #  1  SEC #2  DR#  1 

SEC #3  DR#2  . .  . 

Copies  block  of  sectors  SEC#1  through 
SEC #2  on  drive  DR#1  to  the  block 
starting  at  sector  SEC #3  on  drive  DR #2. 
Warning:  No  check  is  made  to  check  the 
block  start  address  SEC #3  for  potential 
overlap  with  existing  named  files. 

DE  DR #  1  .  .  .  . 

Deletes  the  specified  named  directory 
entry  on  the  specified  drive  DR#1.  File 


name  is  prompted.  Deletes  the  directory 
entry  only.  Does  not  access  the  disk  file 
region  in  any  way;  consequently  this 
command  may  be  used  to  change  the  file 
parameters  (see  CRF  command). 

FILE  #SCIRNS  DR #  1  FILE 

FILE-NAME 

BYTE#  DR #  1 
FILE-NAME 

At  definition  time,  FILE  creates  a  named 
type  5  Forth  data  file  in  the  directory  of 
the  specified  drive.  When  FILE-NAME  is 
executed,  the  stack  will  contain  the  RAM 
address  of  the  specified  byte  on  the  stack. 
At  definition  time,  a  check  is  made  for 
potential  disk  overflow.  The  command 
aborts  on  such  an  eventuality.  Likewise,  a 
pre-existing  file  of  that  name  on  the  drive 
will  abort  the  file  definition,  i.e.,  dupli¬ 
cate  file  names  on  the  same  drive  are  not 
permitted.  Insufficient  directory  space 
also  aborts  the  command.  Caution:  No 
check  is  made  on  the  range  of  the  speci¬ 
fied  byte.  The  purpose  of  this  word  is  to 
allow  disk  data  files  to  be  created  and 
manipulated  in  Forth  source  programs. 
Files  created  using  this  word  cannot  be 
accessed  by  the  LIST-FILE  and  LOAD- 
FILE  commands.  (An  example  using  FILE 
is  shown  in  Figure  1  on  this  page.) 

LI  DR  #  1  ...  . 

Lists  the  directory  of  the  specified  drive 
in  North  Star  format,  that  is,  file  name, 
sector  start,  file  length  in  sectors,  file 
type,  and  load-and-go  address  if  file  is  of 
type  1 . 

LI.S  DR  #  1 _ 

Lists  the  directory  of  the  specified  drive 
in  the  format  file  name,  screen  start, 


1  create-  a  file  16  screens  Iona  on  drive  #2 
10  2  FILE  TST— FILE 

<  write  ASCII  characters-  into  the  file  > 


OPT 


DO 
1  + 


9©  33 
560 
2 

TST -FILE 
I 

SWAP  C! 

LOOP 

FLUSH 


f rotn  ASC 1 1  !  to  2  :> 

<  form  bate  address-  500+1  > 

<  drive  #  > 

i nvoke  file  PAM  addr  > 

<  ASCII  value  to  stack  ') 
r,  store  into  file  > 

<  keep  do i rid  till  2  > 

(  be  sure  file  does  to  the  disk  } 


<  read  the  ASCII  characters  out  to  the  terminal  > 
:  READ  90  33  DO  500  1  +  2  TST -FILE  D8  EMIT  LOOP  i 


Figure  1 . 
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screen  stop,  file  type,  and  load-and-go 
address  if  file  is  type  1 . 

LIST-FILE  DR  #  1 _ 

Used  to  list  the  contents  of  a  Forth  source 
program  file.  Prompts  for  the  name  of  the 
file.  Checks  file  type.  File  type  must  be  4. 

LOAD-FILE  DR#1  .... 

Used  to  load  a  named  Forth  source  pro¬ 
gram  file  from  the  specified  drive.  File 
type  must  be  4. 

ND  DR  #  1  .... 

Provides  a  means  of  uniquely  identifying 
each  diskette  as  the  first  entry  in  the  file 
directory.  It  reserves  the  first  four  sectors 
of  the  disk  for  the  directory.  This  com¬ 
mand  will  overwrite  any  pre-existing  first 
entry.  Prompts  for  the  disk  name. 

Approach 

Several  of  the  commands  described 
above  prompt  the  operator  for  additional 
parameters.  Some  are  forgiving  in  the 
sense  that  they  provide  for  error  recovery 
in  the  event  of  a  syntax  error.  In  the 
event  that  the  error  is  of  the  type  that  is 
not  caught  by  the  routine,  e.g.,  input  of  a 
decimal  number  that  is  unintentional, 
simply  enter  a  space  and  proceed  to  enter 
the  correct  sequence  of  digits  after  the 
error  message.  It  is  for  this  reason  that 
(word)  and  (number)  are  not  used  in  the 
routines.  In  addition,  the  error  messages 
have  been  made  a  part  of  the  definition 
to  avoid  the  necessity  of  maintaining  the 
master  diskette  in  drive  one,  as  would  be 
the  case  if  “message”  had  been  used. 

The  North  Star  DOS  provides  a  num¬ 
ber  of  useful  routines  through  a  jump 
table  at  the  beginning  of  DOS: 

DLOOK  searches  directory 
for  a  file  name. 

DWRIT  writes  directory 
back  to  disk. 

DLIST  lists  the  directory. 

DCOM  reads  or  writes  to  disk. 

In  the  initial  approach  to  a  file  system 
development,  maximum  use  was  made  of 
these  routines.  This  approach  was  ulti¬ 
mately  abandoned  principally  because  it 
severely  reduced  the  portability  of  the 
end  result.  The  file  system  presented  here 
is  written  entirely  in  high-level  Forth 
with  the  exception  of  the  READ/WRITE 
to  the  disk.  This  function  is  accomplished 
by  means  of  code  word  linkage  to  DCOM. 
As  a  result,  the  current  design  should 
prove  useful  on  systems  other  than  the 
North  Star  disk  system. 

Description  of  Disk 
and  Directory  Formats 

The  North  Star  disk  format  consists 
of  35  tracks  of  10  sectors  per  track  fora 
total  of  350  sectors  per  diskette.  They  are 
numbered  from  0  to  349  inclusive.  Each 
sector  consists  of  256  bytes.  The  first 


four  sectors  (=  1024  bytes  =  1  screen)  are 
reserved  for  the  directory.  There  is  a  max¬ 
imum  of  64  entries.  Each  entry  consists 
of  16  bytes.  Bytes  0-7  are  the  name  made 
up  of  from  one  to  eight  of  any  printing 
ASCII  characters  and  filled  with  trailing 
blanks  for  names  less  than  eight  charac¬ 
ters  long.  Note  that  this  generalizes  the 
name  convention  of  North  Star.  Bytes  8-9 
(lo-hi)  are  the  binary  decimal  value  of  the 
disk  sector  start  address  of  the  file.  Bytes 
10-11  (lo-hi)  are  the  binary  decimal 
value  of  the  length  of  the  file  in  sectors. 
Byte  12  is  the  binary  value  of  the  file 
type.  North  Star  has  defined  0  as  the  de¬ 
fault  type,  1  for  executable  object  code, 
2  for  BASIC  source  programs,  and  3  for 
BASIC  data  files. 

This  Forth  file  system  further  defines 
a  Forth  source  program  file  as  type  4,  and 
a  Forth  data  file  as  type  5.  Bytes  13-15 
are  type  dependent.  In  particular,  for  a 
file  of  type  1 ,  bytes  1 3  - 14  (lo-hi)  are  the 
hexadecimal  RAM  address  of  file-load 
and  start-of-execution,  and  byte  15  is 
unused. 

The  North  Star  disk  and  directory 
formats  are  adhered  to  in  this  Forth  file 
system  so  that  disk  directories  may  be 
read  and  utilized  in  DOS  and  BASIC. 
Since  Fig-Forth  assumes  512  bytes  per 
block,  two  blocks  per  screen,  manipula¬ 
tion  of  a  directory  entry  must  observe  the 
conversion  factors  that  there  are  two  sec¬ 
tors  per  block  and  four  sectors  per  screen. 

Deletion  of  a  directory  entry  is  ac¬ 
complished  by  replacing  the  entry  with 
sixteen  blanks.  The  disk  file  is  left  un¬ 
touched;  that  is,  it  is  recoverable  in  the 
event  of  accidental  erasure  of  its  direc¬ 
tory  entry.  Similarly,  creation  of  an  entry 
does  not  alter  the  disk  elsewhere;  hence 
increasing  the  length  of  a  file  or  changing 
other  file  descriptive  parameters  may  be 
accomplished  by  erasing  its  name  from 
the  directory  and  recreating  the  file  name 
with  the  new  file  parameters. 

Directory  entries  for  Forth  source 
files  are  created  by  operator  keyboard  in¬ 
put  of  screen  start  and  screen  stop.  It  is 
assumed  that  such  source  files  are  a  set  of 
contiguous  screens  on  the  same  disk.  In 
keeping  with  the  general  permissiveness 
of  Forth,  no  check  is  made  that  the 
screen  numbers  are  valid.  However,  all 
screen  numbers  are  converted  to  the 
proper  sector  numbers. 

On  the  other  hand,  creation  of  a 
Forth  data  file  is  inhibited  if  its  length 
would  cause  a  disk  overflow,  and  the 
copy  file  command  (CF)  will  also  abort  if 
it  would  lead  to  disk  overflow. 

The  fact  that  the  directory  is  in 
terms  of  file  sector  start  and  file  sector 
length  is  not  very  convenient  for  use  in 
Forth.  Therefore,  two  ways  of  listing  the 
directory  have  been  prepared,  either  in 
terms  of  sectors  or  in  terms  of  screens. 

Finally,  it  should  be  noted  that  this 
file  system  was  generated  for  a  single ¬ 


density  disk  system.  Accordingly,  some 
changes  will  be  required  in  word  defini¬ 
tions  where  higher,  or  mixed,  density  is 
involved. 

The  attached  listing  (page  42)  com¬ 
piles  to  3933  bytes.  Somewhat  less  mem¬ 
ory  is  required  if  DCOM  of  screen  89  is 
not  required. 

Notes  on  the  Listing 

Since  the  listing  is  rather  sparsely 
commented,  the  following  is  offered  as 
an  aid  to  understanding  the  file  system. 
In  screen  88  a  few  convenient,  but  not 
necessarily  essential,  constants  and  varia¬ 
bles  have  been  defined.  Their  main  excuse 
for  existence  is  as  a  mnemonic  aid  for  re¬ 
reading  the  listing  six  months  from  now. 

Screen  89  defines  the  only  CODE 
word  used  in  the  file  system.  It  links  to 
the  North  Star  DOS  routine  of  the  same 
name  in  order  to  perform  disk  READ/ 
WRITE  operations.  It  is,  of  course,  disk 
system  peculiar.  At  the  time  that  this 
system  was  developed,  there  was  no  docu¬ 
mented  word  of  similar  nature  from 
Omniforth.  Since  then,  Omniforth  has 
circulated  a  newsletter  on  RWDSK,  a  pre¬ 
viously  undocumented  word  in  Omniforth 
which  behaves  in  an  identical  fashion  to 
DCOM.  I  have  left  DCOM  in  the  listing  in 
order  to  illustrate  how  such  a  linkage  is 
effected,  but  am  now  using  RWDSK  on 
my  own  system.  (Why  waste  memory?) 

The  input  utilities  GET-NUM,  GET- 
HEX,  and  GET-NAME  are  used  to  allow 
error  recovery  and  operator  command 
abort  during  command  prompt  input. 

The  routine  7ENTRY  in  screen  98 
prompts  the  operator  for  a  file-starting 
screen,  the  last  screen  of  the  file,  and  the 
file  type.  If  the  file  is  type  1,  the  opera¬ 
tor  is  further  prompted  for  a  hexadecimal 
load-and-go  address. 

The  routine  7EMPTY  in  screen  99 
searches  for  an  empty  location  in  the 
directory.  It  expects  to  find  the  RAM 
address  of  the  directory  in  the  variable 
SAVE.  If  an  empty  location  is  found,  the 
variable  BUFR  will  contain  the  RAM 
start  address  of  the  empty  location  and 
a  true  flag  will  be  on  the  stack.  Failure 
to  find  an  empty  location  will  leave  a 
false  flag  on  the  stack. 

The  routine  COMPARE  in  screen  100 
compares  two  strings  for  equality.  It  ex¬ 
pects  ADDR1  ADDR2  LENGTH...  on 
the  stack.  It  leaves  a  false  flag  on  the 
stack  if  the  strings  are  not  equal,  a  true 
flag  if  equal;  now  ADDR1  points  to  the 
byte  following  the  string  associated  with 
the  original  value  of  ADDR1;  and  ADDR2 
has  been  dropped. 

The  routine  FIND-FILE  in  screen 
101  uses  COMPARE  to  locate  the  file 
name  in  IBUF  within  the  directory.  On 
success  there  is  a  true  flag  on  the  stack 
and  the  variable  BUFR  contains  a  pointer 
to  the  byte  following  the  located  name  in 
the  directory.  On  failure,  there  is  a  false 
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flag  on  the  stack.  The  name  was  placed  in  and  then  writing  the  updated  directory  DISK-ALLOT  is  used  by  FILE  to 

IBUF  by  GET-NAME.  back  to  disk.  DO-ENTRY  first  checks  for  build  a  type  5  file  entry  and  put  it  in  the 

WRITE-DIREC  in  screen  101  expects  an  emPty  1(>cation  inuthe  directory  and  if  directory, 

the  variable  SAVE  to  contain  the  pointer  °nb  15  ound>  moves  the  contents  of  IBUF  ?SpACE  Qf  screen  1Q5  is  used  to 

to  the  start  of  the  directory  in  RAM  to  the  location  pointed  to  by  the  contents  make  sure  that  the  file  being  created  or 

memory.  SAVE  was  initialized  by  RD-  °  !r  dlrectory  ls  tben  wntten  written  to  a  disk  will  not  cause  a  disk 
DIREC  as  is  the  drive  pointer  variable  bac*  to  dislc-  overflow. 

DR.  WRITE-DIREC  writes  the  updated  NXT-SEC#  of  screen  104  locates  ,  J  u  u  .  r 

directory  back  to  disk.  DELETE-ENTRY  the  next  free  sector  address  above  the  u  ,  “  “  h°Ped ‘hat  thef  br‘ef  notes  wdl 

expects  the  contents  of  BUFR  to  point  to  “highest”  file  in  the  directory.  Note  that  hedp  *h?  reader  to  decipher  those  routines 

the  entry  to  be  deleted.  The  entry  is  de-  the  diskettes  are  not  “squished”  when  a  which  have  not  been  annotated  on  the 

leted  by  filling  that  location  with  16  blanks  file  is  deleted  from  the  directory.  screens. 


Fig-Forth  Directory  &  File  System 

(Text  begins  on  page  38) 

SCR  #  88 

0  <  CONSTANTS,  VARIABLES,  $<  CONVERSION  FACTORS  > 

1 

2 

3  48  CONSTANT  "0"  57  CONSTANT  "9"  65  CONSTANT  "A" 

4  70  CONSTANT  "F"  90  CONSTANT  "2"  3  CONSTANT  CNTRL-C 

5  HEX  2020  CONSTANT  BLBL  DECIMAL  <  A  DBL.  BLANK  > 

6 

7 

8  0  VARIABLE  BUFR  0  VARIABLE  FLAG  0  VARIABLE  SAVE 

9  0  'JAR  I  ABLE  CNTR  0  VARIABLE  DR  0  VARIABLE  DU 

10  0  VARIABLE  #SEC  0  VARIABLE  LAST-SEC  0  VARIABLE  SECR 

11  O  VARIABLE  SECU 

12  <  5CRN2SEC  SCR#  . . .  SEC#  !> 

13  :  SCRN2SEC  87  /MOD  DROP  4  *  l 

14  <  SEC2SCRN  SEC#  DR#  . . .  SCR#  > 

15  :  5EC2SCRN  1-  87  *  SWAP  4  /MOD  SWAP  DROP  +  J  — > 


SCR  #  89 

0  <:  DCOM  -  LINKAGE  TO  DISK  READ/UR  I TE  ROUTINE  OF  NORTH  STAR  DOS  > 

1 

2  <  DCOM  -  RAM-ADDR  SEC-STRT  #SEC  R/W  DR#  _  > 

3  <  R/W=l  FOR  READ,  =0  FOR  WRITE  > 

4 

5  HEX  CODE  DCOM 

6  I'  L  MOV  I  H  MOV  <  PRESERVE  II'  !> 

7  XTHL  L  I  ■'  MOV  <  DR#  TO  C  > 

8  H  POP  XTHL  L  I  MOV  <  R/W  TO  B  > 

9  H  POP  XTHL  L  A  MOV  <  #SEC  TO  ACC  > 

10  H  POP  XTHL  XCHG  •;  DSK  ADDR  TO  DE  !> 

11  H  POP  XTHL  XCHG  <  RAM  ADDR  TO  DE,  DSK  ADDR  TO  HL  > 

12  2022  CALL  I  POP  <  CALL  DCOM  &  RSTR  II'  > 

13  0  H  MV I  CS  IF  1  L  MV I  ELSE  O  L  MV I  END IF  <  ERROR  FLAG  > 

14  H  PUSH  NEXT  JMP  DECIMAL 

15  — > 
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SCR  #  90 

0  <  LI  A  LI.S  > 

1  <  THERE  ARE  TWO  D I  RECTOR  V  LISTING  COMMANDS ..  LI  A  LI.S  ’> 

2  C  LI  LISTS  THE  D I RECTOR V  IN  NORTH  STAR  FORMAT,  THAT  IS  > 

3  <  NAME,  SECTOR  START,  FILE  LENGTH  IN  SECTORS,  FILF  TVPE  > 

4  <  A  GO  ADDRESS  IF  APPLICABLE.  THE  LI.S  COMMAND  RFPI  ACES  '> 

5  C  THE  SECTOR  INFORMATION  WITH  SCREEN  START  &  SCREEN  STOP  > 

6 

7  <  DR-TST  -  DR#  ...  DR#  ABORTS  IF  DR#  OUT  OF  RANGE  > 

8  :  DR-ERR  CR  . "  DR#  ERROR  "  CR  ABORT  i 

9  :  DR-TST  DUP  1  <  IF  DR-ERR  ELSE  DUP  3  >  IF  DR-ERR 

10  END IF  END IF  i 

11 
12 

13  :  RD-DIREC:  0  BUFFER  DUP  DUP  SAME  !  BUFR  !  0  4  1  DR  *9 

14  DCOM  DISK-ERROR  I  ; 

15  — > 


SCR  #  91 

0  <  LI  A  LI.S  CONTINUED  > 

1  :  7SCRN  FLAG  <9  IF  DR  '9  SEC2SCRN  END  IF  J 

2  :  LIST-DIREC  BUFR  -9  16  BUFR  +  !  DUP  S  TVPE  8  +  DUP  -9  DUP 

3  2  SPACES  7SCRN  3  .R  2  SPACES  SWAP  2+  DUP  -9  ROT 

4  FLAG  <9  IF  +  7SCRN  1-  ELSE  DROP  END  IF  3  .R  2  SPACES  2+  DUP  C< 9 

5  DUP  3  .R  1  =  IF  2  SPACES  1+  -9  .  4H  ELSE  DROP  END  IF 

6  :  DOUT  BUFR  '9  >9  BLBL  =  IF  16  BUFR  +!  ELSE  LIST-DIREC  CR  END  IF  ; 

7  :  .LI  CR  DR-TST  DR  !  FLUSH  EMPTV-BUFFERS  RD-DIREC  CR  0  CNTR  ! 

8  BEGIN  CNTR  -9.  1  CNTR  +  !  64  <  WHILE  DOUT  REPEAT  ; 

9 

10  <  LI.S  -  DR#...  LISTS  FNAME , SCR#  STRT,SCR#  STOP, TVPE, G A  > 

11  :  LI.S  1  FLAG  !  .LI  1 

12 

13  <  LI  -  DR#  ...  LISTS  FNAME, SEC#  STRT, FILE  LEN , TVPE , GA  > 

14  :  LI  0  FLAG  !  .LI  ; 

15  — > 


SCR  #  92 

0  <  THE  CD  COMMAND  > 

1  <  CD  DR#1  DR# 2  ...  > 

2  <  COPIES  ENTIRE  DISKETTE  ON  DR#1  TO  DISKETTE  ON  DR#2  > 

3 

4  :  NEXT-SEC  #SEC  -9  DUP  SECR  +!  SECW  +!  LAST-SEC  -9  SECR  >9 

5  #SEC  <9  +  -  DUP  0<  IF  #SEC  +!  ELSE  DROP  END  IF 

6  #SEC  -9  0=  ; 


9  :  DWRITE  LIMIT  SECW  '9  #SEC  <9  O  DW  -9  DCOM  DISK-ERROR  ! 

10  :  DREAD  LIMIT  SECR  '9  #SEC  >9  1  DR  -9  DCOM  DISK-ERROR  1 

11 

12  <  ABORT  COMMAND  ON  A  CNTRL-C  > 

13  :  7ABORT  CNTRL-C  =  IF  DROP  QUIT  ELSE  DUP  END  IF 

14 

15  — > 


(Listing  continued  on  next  page) 
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Fig-Forth  Directory  &  File  System 

(Listing  continued,  text  begins  on  page  38) 

SCR  #  93 

0  <  THE  CD  COMMAND  CONTINUED  > 

1  <  THE  WORD  SET— #SEC  FINDS  THE  P.UAILABLE  NUMBER  OF  SECTORS  > 

2  <  ABOUE  I-IMIT  THAT  CAN  BE  USED  AS  A  DISK  BUFFER.  NORMALLV  > 

3  <  THE  TOP  OF  MEMORV  IS  A  CONSTANT,  BUT  NOT  IN  MV  SYSTEM!!  > 

4  :  SET— #SEC  LIMIT 

5  BEGIN  256  +  DUB  DUP  O  SWAP  !  * 

6  -1  =  UNTIL 

7  256  -  LIMIT  -  256  ✓  DUP  32  >  IF  DROP  32  END IF  #SEC  !  ; 

8  <  THE  WORD  DCOPV  IS  COMMON  TO  CD  AND  CSEC  > 

9  :  DCOPV  BEGIN  DREAD  DWRITE  NEXT-SEC  UNTIL 

10  CR  . "  COPV  COMPLETED  "  CR  ; 

11  :  CD  SWAP  DR-TST  DUP  DR  !  . "  COPV  FRM  DSK  "  .  DR-TST 

12  DUP  DW  !  .  "  TO  DSK  ”  .  CR 

13  HIT  SPACE  BAR  TO  CONTINUE,  ANV  OTHER  TO  ABORT  " 

14  KEV  32  IF  CR  356  LAST-SEC  !  6  DUP  SECR  !  SECW  ! 

15  SET— #SEC  DCOPV  ELSE  . ”  CMND  ABORTED  "  CR  END IF  }  — > 


SCR  #  94 

0  <  THE  CSEC  COMMAND  > 

1  <  CSEC  SEC#1  SEC #2  DR#1  SEC#3  DR#2  ...  > 

2  <  COPIES  SEC:#1  THRU  SEC#2  FROM  DRIUE  DR#  1  TO  DR#2  > 

3  <  STARTING  AT  SEC#3.  !> 

4 

5  :  CSEC  DR-TST  DW  !  SECW  !  DR-TST  DR  '  1+ 

6  LAST-SEC  !  SECR  !  SET-#SEC  LAST-SEC  «  SECR  « 

7  -  DUP  #SEC  «  <  IF  #SEC  !  ELSE  DROP  END  IF  DCOPV 

8 

9  <  THE  FOLLOWING  SEUERAL  SCREENS  DEUEL  OP  A  SET  OF  UTILITIES.  !> 

10  <  THE  WORD  BUFF  IS  USED  TO  CREATE  TEMPORARY  HOLDING  BUFFERS  > 

11  <  FOR  COMMAND  PARAMETER  INPUT.  ) 

12 

13  <  BUFF  -  N1  BUFF  NAME  ALLOTS  N1  BYTES  TO  NAME  > 

14  :  BUFF  < BUILDS  ALLOT  DOES>  ; 

15  16  BUFF  IBUF  16  BUFF  TBUF  — > 


SCR  #  95 

0  <  GET-NUM  LEAUES  DECIMAL  #  ON  TOP  OF  STACK  > 

1  :  SVN-ERR  CR  . "  SYNTAX  ERROR  "  DROP  DROP  6  "0"  CR  i 

2  :  GET-NUM  6  FLAG  !  <  QUIT  WHEN  FLAG  =  1  !> 

3  6  EEGIN  <  PUT  INITIAL  #  =  0  ON  TOP  OF  STACK  > 

4  KEV  DUP  DUP  EMIT  7AB0RT  <  GET  CHR  &  ECHO  IT  > 

5  13  =  IF  1  FLAG  !  DROP  <  QUIT  ON  A  CR  > 

6  ELSE  DUP  "0"  <  IF  <  CHR  <  6  ?  > 

7  SVN-ERR 

8  ELSE  DUP  "9"  >  IF  <  CHR  >  9  ?  > 

9  SVN-ERR  END IF  END IF  END IF 
18  <  NOW  CNUT  ASCII  TO  DECIMAL  &  ADD  TO  THE  STACK  > 

11  FLAG  «  6=  IF  48  -  SWAP  10  *  +  END IF 

12 

13  FLAG  UNTIL  ;  <  KEEP  GOING  TILL  CR  > 

14 

15  — > 
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SCR  #  96 

0  ■;  GET— HEX  LEflUE  O  HEX  #  OH  TOP  OF  STOCK  > 

1 

2 

3 

4  :  GET-HEX  0  FLOG  !  8  BEGIN  KEV  DUP  DUP  EMIT  ?RBOPT 

5  13  =  IF  1  FLOG  !  DROP 

6  ELSE  DUP  "0"  <  IF  SVN-ERR 

7  ELSE  DUP  "9"  >  IF  DUP  "0”  <  IF  SVN-ERR 

8  ELSE  DUP  "F”  >  IF  SVN-ERR  END IF 

9  END IF  END IF  END IF  END IF 

10  FLOG  -3  0=  IF  48  -  DUP  9  >  IF  7  -  END  IF  SWOP  16  *  +  END  IF 

11 

12  FLOG  «  UNTIL  ; 

13  — > 

14 

15 


SCR  #  97 


GET— NOME  > 

INIT-IBUF  IESUF  DUP  BUFR  !  S  CNTR  !  8  FLOG  !  IBUF  16  PLONK! 
NM— ERR  CR  . "  SVNTOX  ERROR  "  CR  . "  REENTER  FNOME  " 

DROP  DROP  INIT-IBUF  ; 

GET— NOME  INIT-IBUF  . “  FNOME?  " 

BEGIN  KEV  DUP  DUP  EMIT  70B0RT 
13  =  IF  1  FLOG  !  DROP 

ELSE  DUP  33  <  IF  NM-ERR 

ELSE  DUP  "Z"  >  IF  NM-ERR 


END  IF 

END IF  CNTR  «  0=  IF  1 
FLOG  S  UNTIL  DROP  CR  ; 

—  > 


FLOG 


>  IF  NM-ERR 
ELSE  BUFR 
+!  C !  -1 
END  IF 

END  IF 


*  1  BUFR 
CNTR  +' 


SCR  #  9S 

6  C  7ENTRV  AND  CLR-SCR  > 

1 

2  :  7ENTRV  . "  SCR  STRT?  "  GET-NUM  CR  DUP  SCRN2SEC 

3  IBUF  S  +  DUP  2+  BUFR  !  ! 

4  . "  LOST  SCR?  ”  GET-NUM  CR  SWOP  -  1+  4  * 

5  BUFR  !  2  BUFR  +! 

6  ."FILE  TVPE?  "  GET-NUM  CR  DUP  DUP  5  =  IF 

7  . "  WRONG  FILE  TVPE  "  CR  ABORT  ELSE  BUFR  *  C !  1 

8  BUFR  +  !  END IF 

9  1  =  IF  .  "  HEX  GO  ODDR?  "  GET-HEX  CR  BUFR  *  !  END  IF  ; 

10 

11  <  CLR-SCR  -  SCR# 1  SCR#2  _  CLEARS  SCR#1  THRU  SCR#2  > 

12 

13  :  CLR-SCR  1+  SWOP  DO  I  EDITOR  CLEAR  FORTH  LOOP  J 

14 

15  — > 

(Listing  continued  on  page  46) 
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Fig-Forth  Directory  &  File  System 

(Listing  continued,  text  begins  on  page  38) 

SCR  #  99 

0  <  ?EMPTV  > 

1  :  7'EMPTV  0  DUP  CNTR  i  FLRG  !  SftUE  -8  BUFR  ! 

2  BEGIN  1  CNTR  +!  BUFR  *8  16  BUFR  +! 

3  «  BLBL  =  IF  -16  BUFR  +!  1  FLftG  ' 

4  ELSE  CNTR  >8  65  =  IF 

5  1  FLftG  !  END IF  END IF 

6  FLftG  -8  UNTIL 

7  CNTR  «  65  =  IF  0  ELSE  1  END IF  i 

8 
9 

10  — > 

SCR  #  10© 

0  <  COMPARE  > 

1  :  COMPARE  1  FLftG  ! 

2  0  DO  DUP  08  ROT  DUP  C<8  ROT 

3  =  IF  1  +  SWAP  1+  ELSE  0  FLftG  !  END IF  LOOP 

4  SWAP  DROP  FLftG  «  DUP  0=  IF  SWAP  DROP  END IF  J  — > 

5  <  COMPARE  TWO  STRINGS  RDDR1  ftDDR2  CNT  ON  STACK, 

6  LEAUE  0  ON  STACK  IF  NOT  EQUAL,  1  IF  EQUAL  A  RDDR1  PNTS 

7  TO  CELL  FOLLOWING  NAME  > 

8 
9 

10 - > 


SCR  #  101 

0  <  FIND-FILE  WRITE-DIREC  DELETE— ENTRV  DO-ENTRV  > 

1  :  FIND-FILE  O  CNTR  !  SftUE  *8  BUFR  !  0  FLftG  ! 

2  BEGIN  1  CNTR  +!  IBUF  BUFR  -8  16  BUFR  +!  8 

3  COMPARE 


4  IF  DROP  -16  BUFR  +!  1  FLftG  !  END IF 

5  CNTR  -8  65  =  IF  1  FLftG  !  END  IF 

6  FLftG  -8  UNTIL 

7  CNTR  -8  65  =  IF  6  ELSE  1  END  IF  ; 

8 

9  :  WRITE-DIREC  SftUE  '8  O  4  6  DR  >8  DCOM  DISK-ERROR 


10 

11  :  DELETE -ENTRV  BUFR  -8  16  BLRNKS  WRITE-DIREC  ; 

12 

13  :  DO— ENTRV  7EMPTV  IF  IBUF  BUFR  -8  16  CMOUE  WRITE-DIREC 

14  ELSE  CR  . "  DIRECTORY  IS  FULL  "  CR  QUIT 

15  END IF  i  — > 


8  <  DE  > 

1  DE  -  DR#  .  .  .  PROMPTS  FOR  FNftME  > 

2  •;  USED  TO  DELETE  NAMED  FILES  FROM  THE  DIRECTORS'  OF  THF  > 

3  <  SPECIFIED  DRIUE  DR#  !> 

4 

5  :  CHK-NAME  DR-TST  DR  !  RD-DIREC  GET-NAME  CR  FIND-FILE 

6  :  DE  CHK-NAME  IF  DELETE— ENTRV  ELSE  . "  FILE  NOT  FOUND  " 

7  CR  END IF  i 

8  — > 
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0 

1 

2 

3 

4 

5 

6 
-7 

I 

8 

9 

10 

11 

12 


LIST-FILE  > 

LIST-FILE  -  DR#  ...  PROMPTS  FOR  FILE  NAME  > 

USED  TO  LIST  NAMED  FILE  FROM  THE  SPECIFIED  DR IMF  > 
WILL  ACCEPT  FORTH  SOURCE  PROGRAMS  OF  TVPE  4  OHLV  > 

:  .FF  12  EMIT  ;  > 

LI ST -FILE  CHK— NAME  IF  BUFR  '8  DUP  12  +  08  4  =  IF  . FF  8 
DUP  -8  4  /  DR  <8  1-  87  *  +  SWAP  2+  >8  4  / 

0  CNTR  !  0  DO  CNTR  >8  3=  IF  .  FF 
0  CNTR  !  END IF  DUP  LIST  1+  1  CNTR  +!  LOOP 
DROP  .FF  ELSE  DROP  . "  WRONG  FILE  TVPE  "  CR 
QUIT  END IF  ELSE  CR  . "  FILE  NOT  FOUND  "  CR  END IF 


>CR  # 


4 

5 

6 
I 

8 

9 

10 

11 

12 

13 

14 

15 


104 

NXT-SEC# 
NX  T- SEC# 


> 

RD-DIREC  0  DUP  DUP  CNTR  1 

BEGIN  1  CNTR  +!  BUFR  -8  16  BUFR  +! 

DUP  <8  BLBL  =  IF  DROP 

ELSE  8  +  DUP  -8  SWAP  2+  >8  +  DUP  ROT 

>  IF  SWAP  DROP  DUP  ELSE  DROP  DUP  END IF 


>8  65 
I BUF 
10  + 


UNT 1 1 
+  ! 


DROP 


END IF  CNTR 
DISK- ALLOT  I BUF  16  BLANKS 
4  *  I BUF  5  OUER  12  +  C! 

DUP  1+  SWAP  08  31  AND 
I BUF  SWAP  DUP  >R  CMOUE  R>  I BUF  +  1-  DUP  08 
FIND-FILE  IF  CR  . "  FILE  NAME  CONFLICT  " 
DO-ENTRV  END IF  i 


.127 

CR 


'  AND 
QUIT 


SWAP  C 
EL.  SE 


SCR  #  105 
0  <  FILE  > 

1  <  #SCRNS  DR#  FILE  FNAME  > 

2  <  BYTE#  DR#  FNAME  L.EAUES  RAM  ADDR  OF  BVTF#  > 

—r 

4  <  7SPACE  #SC:RNS  SEC-STRT  .  .  .  #SCRNS  SEC-STRT  1  > 

5  <  #SCRNS  SEC-STRT  ...  0  > 

6  :  7SPACE  2DUP  SWAP  4  *  +  350  >  IF  DROP  DROP  DROP  0 

7  ELSE  1  END IF  J 

8 

9  :  FILE  DR-TST  DR  !  HERE  SWAP  NXT-SEC#  7SPACE 

10  0-  IF  . ”  INSUFFICIENT  DISK  SPACE  ”  CR  QUIT  END IF 

11  < BUILDS  DUP  ,  DISK— ALLOT 

12  DOES>  -8  SWAP  DUP  DR  !  1-  174  *  SWAP  2  + 

13  SWAP  512  /MOD  ROT  +  BLOCK  +  UPDATE  i 

14 

15  — > 


SCR  #  106 
0  <  ND  > 

1  <  ND  -  DR#  . . .  PROMPTS  FOR  D I SK  NAME  > 

2  <  PROUIDES  A  MEANS  OF  UNIQUELV  IDENTIFYING  EACH  DISK  > 

(Listing  continued  on  next  page) 
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Fig-Forth  Directory  &  File  System 

(Listing  continued,  text  begins  on  page  38) 

3  <  AS  THE  FIRST  ENTRV  IN  THE  DIRECTORS'.  IT  RESERUES  > 

4  >C  THE  FIRST  4  SECTORS  OF  THE  DISK  FOR  THE  DIRECTORS'.  > 

5  <  THIS  COMMAND  WILL  OUERWRITE  ftNS'  PRE-EXISTING  FIRST  ENTRS'.  > 

6 

7 

8  :  ND  DR-TST  DR  !  RD-DIREC  GET-NAME  IBUF  SAME  -S'  8  CMOUE 

9  SAME  <8  8  +  DUP  0  SWAP  !  2+  DUP  4  SWAP  ! 

10  2+  DUP  0  SWAP  C!  1+0  SWAP  !  WRITE-DIREC:  1 

11 
12 

13 

14 

15  — > 


SCR  #  107 

8  <  CSCR  > 

1  <  CSCR  -  SCR#  1  SCR# 2  SC:R#3  ...  > 

2  <  COPIES  FROM  SCR#1  THRU  SCR#2  TO  SCR#3  &  UP  > 

3 

4 

5 

6 

7 

8 

9  :  CSCR  SECW  !  1+  SWAP  DO  I  SECW  >4!  1 

10  SECW  + !  EDITOR  COPS’  FORTH  LOOP  J 

11  — > 

SCR  #  168 
0  ■;  CRF  > 

1  <  CRF  -  DR#  . . .  PROMPTS  FOR  OTHER  PARAMETERS  > 

2  •:!  USED  TO  CREATE  DIRECTORS’  ENTRIES  FOR  ANS’  FILE  TS'PE  > 

3  <  EXCEPT  TS'PE  5,  THAT  FORTH  DATA  FILES  ARE  INHIBITED.  > 

4 

5 

6  :  CRF  DR-TST  DR  !  RD-DIREC  GET-NAME  2ENTRV  FIND-FILE 

7  IF  CR  .  "  FILE  AL.READV  EXISTS  ”  CR 

8  ELSE  DO-ENTRV  END IF  ; 

9  — > 

SCR  #  109 

0  <  LOAD-FILE  > 

1  <  LOAD-FILE  -  DR#  _  PROMPTS  FOR  FNAME  > 

2  <  USED  TO  LOAD  FORTH  SOURCE  PROGRAM  FILES.  > 

3  <  ACCEPTS  TS'PE  4  FILES  ONES'.  > 

4 

5 

6 

7  :  LOAD-FILE  CHK— NAME 

8  IF  BUFR  8  +  '*  DR  «  SEC2SCRN  LOAD 

9  ELSE  CR  . ”  FILE  NOT  FOUND  "  CR  END IF  J 
10  — > 
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SCR  #116 

&  <:  cf  > 

1  <  CF  -  DR#1  DR# 2  ...  PROMPTS  FOR  FILF  NAMES  > 

2  <  COPIES  SPECIFIED  FILE  FROM  DR  I  ME  DR#1  TO  SPECIFIED  !> 

3  <  FILE  ON  DRIUE  DR#2.  FILE  NEED  NOT  EXIST  ON  DR# 2,  > 

4  <  SINCE  ROUTINE  WILL.  CREATE  THE  NECESSARV  ENTRV  IF  > 

5  <  THERE  IS  ROOM  ON  THE  DISK.  IF  THE  FILE  ALREADV  > 

6  <  EXISTS  ON  DR# 2  THEN  THE  COPV  PROCEEDS  ONLY  IF  THE  > 

7  <  FILE  IS  SUFFICIENTLV  L  ARGE,  THAT  IS  >=  !) 

O 

u 

9  O  URRI ABLE  DT  0  UARI ABLE  DF  16  BUFF  FBUF 

10  :  WRITE-SEC  FBUF  S  +  DUP  >3  <  START  SEC  > 

11  DUP  ROT  2+  <3  +  1-  <  LAST  SFC  > 

12  DF  -3  <  FROM  DRIUF  > 

13  TBUF  S  +  -3  <  FIRST  TO-SECTOR  > 

14  DT  -3  <  TO-DRIUE  > 

15  CSEC:  <  XFR  SECTORS  >  j  — > 


SCR  #111 

6  (  CE  CONTINUED  > 

1  :  CF  SWAP  DUP  FROM  DRIUE  "  .  . "  &  FROM  "  CHK— NAME 

2  IF  DR  -3  DF  !  BUFF:  -3  FBUF  16  CMOUE  <  ENTRV  TO  FBUF,  DF  > 

3  ELSE  ."  FIL.E  NOT  FOUND  "  CR  QUIT  END  IF 

4  DUP  ."  TO  DRIUE  "  .  . "  &  TO  "  CHK-NAMF 

5  IF  DR  *3  DT  !  BUFF:  >3  TBUF  16  CMOUE  ENTRV  TO  TBUF ,  DT  > 

6  TBUF  10  +  -3  FBUF  10  +  <g  1 - <  LEN  DIFF  =>  0  IS  OK  !) 


S 

9 

10 

11 

12 

13 

14 

15 


IF  WRITE-SEC  QUIT  END IF 
ELSE  <  CREATE  A  NEW  ENTRV  ON  TO-DRIUE  > 

DT  -3  DW  !  FBUF  IBUF  16  CMOUE  NKT-SFC#  DUP  IBUF  8  +  ! 

I BUE  10  +  >3  +  DUP  350  >  IF  .  "  INSUFFICIENT  DISK  ROOM  " 

CR  QUIT 

ELSE  DO— ENTRV  END IF 
<  NOW  WRITE  THE  SECTORS  TO  THE  DRIUF  > 

IBUF  TBUF  16  CMOUE  WRITE-SEC 

END  IF  i  End  Listing 
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SAY” 

Forth  Votrax  Driver” 


Forth  enthusiasts  frequently  cite 
modularity  and  expandability  as  the 
language’s  greatest  strengths.  The 
truth  of  these  claims  can  be  shown  with 
an  example:  Design  of  all  necessary  soft¬ 
ware  to  interface  a  Votrax  Type’N  Talk 
speech  synthesizer  to  a  system. 

BASIC  and  other  “conventional” 
languages  make  such  software  interfaces 
difficult  to  design  and  inconvenient  to 
use.  In  general,  all  or  most  of  the  inter¬ 
face  routine  must  be  written  in  machine 
language;  portability  between  systems, 
even  within  the  same  processor  family,  is 
rare.  The  routine  must  be  explicitly 
included  in  every  program  requiring  use 
of  the  peripheral,  by  either  keying  in  a 
subroutine  or  loading  a  utility  module 
from  mass  storage.  Commands  within  the 
BASIC  program  (let  alone  the  machine 
code  routines)  are  generally  not  self- 
documenting,  with  obscure  references  like 
K=USR(7)  or  X  =  INP(231)  AND  &127 
perhaps  meaning  to  initialize  the  proper 
port  or  check  an  input  bit. 

With  Forth,  though,  the  entire  soft¬ 
ware  interface  can  be  programmed  in 
portable  high-level  code,  with  virtually 
no  penalty  to  execution  speed  and  mem¬ 
ory  requirements.  The  resulting  interface 
is  hardly  an  inelegant  “patch  job,”  as  in 
BASIC;  after  development,  the  interface 
becomes  part  of  the  language,  usable  in 
exactly  the  same  manner  as  any  other 
Forth  “words.”  It  is  even  possible  to 
make  the  interface  software  part  of  the 
core  language,  so  that  it  will  be  available 
immediately  upon  a  cold  start  without  an 
additional  loading  operation.  Perhaps  best 
of  all,  interactive  development  and  testing 
make  the  software  design  process  incred¬ 
ibly  fast  and  efficient  —  in  this  instance, 
the  Votrax  software  was  developed  from 
first  idea  to  final  test  in  under  20  minutes, 
and  still  uses  less  than  100H  bytes  of 
memory. 

The  basic  function  of  such  an  inter¬ 
face  routine  is  to  move  data  from  memory 
to  the  peripheral,  in  accordance  with  the 
data  conventions  of  both  the  language 
and  the  device.  The  Votrax  Type’N  Talk 
is  designed  to  receive  ASCII  data  via  an 
RS-232C  port,  using  any  of  eight  baud 
rates.  At  low  data  speeds,  and  with  short 
and  relatively  infrequent  output  strings, 


by  C.  Kevin  McCabe 


C.  Kevin  McCabe,  115  South  LaSalle, 
Suite  1200,  Chicago,  IL  60603. 


the  physical  interface  does  not  need 
handshaking  lines.  Longer,  faster,  or  more 
frequent  output,  though,  will  overflow 
the  Votrax’s  limited  buffer  unless  hand¬ 
shaking  is  implemented  using  the  Type’N 
Talk’s  Clear  To  Send  line.  In  this  instance. 
Clear  To  Send  is  simply  brought  into  a 
single  control  port  bit  on  a  Vector  Graph¬ 
ics  serial  I/O  board;  other  systems  may 
use  different  handshaking  schemes  appro¬ 
priate  to  the  hardware. 

The  interface  routine  in  Listing  1 
uses  the  Forth  Interest  Group’s  Forth 
(Fig-Forth)  for  the  8080,  release  1.1. 
With  minor  changes  at  most,  the  software 
should  be  portable  to  other  Fig-Forth 
installations  regardless  of  processor  types. 
Only  CLEARTHROAT  and  two  or  three 
integer  constants  in  SAYCHARACTER 
are  system -dependent.  In  this  case, 
CLEARTHROAT  is  defined  to  output  the 
six  data  bytes  shown  in  line  4  of  screen 
500  to  serial  control  port  07H.  These 
bytes  initialize  serial  ports  06H  and  07H 
of  the  I/O  board  for  the  appropriate  word 
size  and  baud  rate.  If  the  system  uses  seri¬ 
al  ports  which  are  integral  to  the  system 
or  initialized  upon  cold  start,  CLEAR¬ 
THROAT  or  its  equivalent  may  not  be 
necessary.  In  any  event,  CLEARTHROAT 
is  only  executed  once,  during  the  loading 
operation. 

The  core  Fig-Forth  language,  available 
after  a  cold  start,  contains  over  a  dozen 
words  for  terminal  output.  Like  most 
of  the  language,  the  “building  block” 
approach  has  been  used  extensively  in 
these  word  definitions.  In  most  instances, 
only  EMIT  (which  takes  an  ASCII  char¬ 
acter  byte  from  the  stack  and  sends  it 
to  the  terminal)  is  defined  as  a  machine- 
language  “primitive;”  all  other  terminal 
output  builds  upon  EMIT  to  output 
strings  and  numerics. 

The  same  scheme  can  be  used  for 
output  to  the  Votrax.  As  defined  in  lines 
11-14  of  screen  500,  SAYCHARACTER 
treats  the  value  currently  on  top  of  the 
stack  as  an  ASCII  character  byte,  and 
outputs  it  to  the  Votrax  (and  optionally 
to  the  terminal  as  well)  with  full  hand¬ 
shaking.  No  machine  code  is  required,  as 
th£  core  Fig-Forth  language  already 
provides  all  necessary  operations  in  high 
level. 

SAYCHARACTER  executes  by  first 
entering  an  indefinite  BEGIN.  .  .UNTIL 
loop  to  read  input  from  port  07H,  repeat¬ 
ing  until  a  Clear  To  Send  signal  is  received. 
For  the  hardware  used  here,  bit  0  on  port 
07H  is  the  handshaking  signal;  a  zero  on 


that  bit  signals  that  the  Votrax’s  input 
buffer  is  full.  The  loop  will  terminate 
whenever  bit  0  goes  to  a  1.  Line  13  dupli¬ 
cates  the  top  stack  value  for  later  use, 
then  outputs  the  copy  to  the  Votrax  via 
serial  port  06H. 

For  convenience,  one  additional  fea¬ 
ture  is  added  to  the  definition  of  SAY¬ 
CHARACTER.  At  times,  it  may  be  neces¬ 
sary  to  send  output  to  both  the  Votrax 
and  the  terminal.  The  most  efficient 
means  is  to  include  a  software  switch  in 
the  lowest-level  output  definition;  in  that 
way,  all  later  words  defined  with  this 
“building  block”  will  use  the  same 
method  to  direct  output,  at  no  additional 
software  cost.  Here,  SAYCHARACTER 
fetches  the  value  of  the  variable  VOICE+ 
PRINT  tor  use  as  a  logical  flag.  A  non¬ 
zero  value  (a  true  flag)  sends  the  remaining 
copy  of  the  character  byte  to  the  termi¬ 
nal,  using  EMIT  for  output.  If  the  flag 
value  is  zero  (false),  the  remaining  copy  is 
simply  dropped  from  the  stack. 

Screens  501  and  502  contain  the  re¬ 
maining  high-level  words  to  incorporate 
ASCII  string  audio  output  capabilities 
to  the  Forth  system;  all  are  system- 
independent,  as  they  are  defined  using 
SAYCHARACTER.  For  ease  of  use,  the 
words  are  defined  similarly  to  the  Fig- 
Forth  core  words  for  terminal  output, 
with  the  same  stack  values  and  formats. 

SPEAK,  like  TYPE  for  terminal 
output  of  strings,  requires  two  operands 
from  the  top  of  the  stack.  The  top  value 
n  is  the  character  count  of  the  string 
whose  first  data  byte  is  at  address  addr. 
Any  non-zero  count  will  fetch  n  ASCII 
characters  one-by-one  from  memory  to 
the  stack,  and  then  send  each  to  the 
Votrax.  If  the  count  byte  is  zero,  SPEAK 
simply  removes  the  address  operand  with¬ 
out  output  of  any  characters.  Since  out¬ 
put  of  individual  characters  uses  SAY¬ 
CHARACTER,  each  may  also  be  directed 
to  the  terminal  by  first  storing  a  true  flag 
value  in  the  VOICE+PRINT  variable. 
Note  that  any  character  string  in  memory 
can  be  output  using  SPEAK,  so  long  as 
the  initial  data  byte  address  and  character 
count  are  first  placed  on  the  stack. 

SAY”  and  (SAY”)  operate  in  tandem 
during  various  phases  of  operation,  in  the 
same  manner  as  the  terminal  output  word 

and  its  (.”)  run-time  procedure. 
Character  strings  delimited  by  a  trailing 
“quote”  character  (22H  =  34  decimal)  are 
input  from  the  terminal,  separated  from 
SAY”  by  one  or  more  blanks.  Further 
execution  of  SAY”  depends  upon  Forth’s 
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current  operating  state;  a  zero  value  for 
the  user  variable  STATE  indicates  that 
Forth  is  executing  rather  than  compiling. 

In  the  execution  state,  lines  10-12  of 
screen  502  move  the  input  string  from 
the  terminal  buffer  to  the  top  of  the  dic¬ 
tionary,  with  a  leading  one-byte  character 
count.  The  current  dictionary  pointer  is 
placed  on  the  stack,  then  used  by  COUNT 
to  increment  the  pointer  and  fetch  the 
contents  of  the  count  byte.  These  two 
values  are  the  operands  for  SPEAK, 
which  output  the  string  to  the  Votrax. 
Again,  VOICE+PR1NT  can  be  used  to 
direct  output  to  the  terminal  as  well. 

When  SAY”  is  encountered  as  a  com¬ 
ponent  word  during  compilation  of  colon 
definition  —  that  is,  in  Forth’s  compilation 
state  —  the  action  is  somewhat  more  com¬ 
plex.  SAY”  is  defined  as  an  immediate 
word,  which  executes  even  during  the  com¬ 
pilation  state.  It  does  not,  though,  cause 
immediate  output  as  during  execution. 
Instead  SAY”  first  compiles  an  address 
pointer  to  the  (SAY”)  run-time  routine. 
The  text  string,  along  with  its  leading 
count  byte,  is  moved  to  the  next  available 
dictionary  locations.  Finally,  the  diction¬ 
ary  pointer  is  incremented  to  the  byte 
beyond  the  end  of  the  string. 

During  later  execution  of  the  colon- 
defined  word,  execution  of  (  SAY”)  will 
output  the  compiled  string.  Fig-Forth 
uses  the  return  stack  to  hold  an  address 
pointer  to  the  next  component  of  a  colon- 
defined  word;  in  this  instance,  the  next 
“word”  is  actually  the  string  compiled 
into  the  definition  by  SAY”.  Lines  1 1 
and  12  of  screen  501  non- destructively 
copy  the  pointer  to  the  string  from  the 
return  stack  and  increment  it  to  designate 
the  first  data  byte.  That  pointer  is  left  on 
the  stack,  along  with  two  copies  of  the 
character-count  byte.  One  copy  of  the 
count  is  incremented  (to  account  for  the 
count  byte  itself),  and  used  in  turn  to 
increment  the  return  stack’s  word  pointer 
to  beyond  the  string.  Finally,  SPEAK  is 
used  to  output  the  string. 

That’s  it  —  all  the  basic  building 
blocks  needed  for  audio  output  of  ASCII 
strings  with  the  Votrax  Type’N  Talk. 
Listing  2  defines  several  other  words 
using  these  fundamental  components,  for 
convenient  output  of  numeric  values  and 
ASCII  text  from  disk  screens.  Again,  all 
are  completely  portable,  and  all  use 
VOICE+PRINT  as  a  software  switch  — 
the  direct  result  of  Forth’s  building  block 
approach. 

SAYLINE  corresponds  to  Fig-Forth’s 
.LINE  and  outputs  line  nl  of  screen  n2  to 
the  Votrax.  Similarly,  SAYSCREEN  out¬ 
puts  an  entire  screen  —  presumably  ASCII 
text,  since  Forth  source  code’s  abbrevia¬ 
tions  and  symbols  don’t  translate  well  to 
audio. 

Single-  and  double-precision  numeric 
stack  values  may  be  output  to  the  audio 


system  with  SAYU,  SAYN,  and  SAYD, 
respectively,  in  the  same  manner  as  U., 
or  D.  for  printed  output.  If  numeric 
output  to  the  terminal  is  desired  as  well, 
it  is  easiest  to  use  separate  voice  and  ter¬ 
minal  output  words  in  this  instance  rather 
than  the  VOICE+PRINT  software  switch. 
As  defined,  SAYD  outputs  a  negative  sign 
as  the  word  “negative”  rather  than  a 
single  character.  In  addition,  digit  charac¬ 
ters  are  output  separated  by  blanks; 
otherwise,  the  Votrax  would  attempt  to 
pronounce  a  value  such  as  OCABH  as  a 
single  word  rather  than  the  desired  “see- 
a-bee.” 

Aside  from  any  necessary  port  ini¬ 
tialization,  only  SAYCHARACTER  will 
require  modification  for  use  on  other  sys¬ 
tems.  Appropriate  values  should  be  used 
for  the  control  port  number  in  line  12 
and  data  port  number  in  line  13  of  screen 
500.  If  the  Votrax’s  Clear  To  Send  con¬ 
trol  signal  is  not  brought  onto  the  I/O 
board  as  bit  0,  it  will  also  be  necessary  to 
change  the  masking  constant  preceding 
the  logical  AND  operation  in  line  12. 

Users  of  the  proposed  Forth-79  ver¬ 
sion  of  the  language  should  note  that 
more  extensive  changes  will  be  necessary. 
Some  Forth-79  words  are  defined  some¬ 
what  differently  than  their  Fig-Forth 
counterparts;  in  other  instances,  no  Forth- 
79  counterpart  exists.  Examples  of  the 
latter  problem  are  the  words  P!  and  P@, 
which  transfer  data  between  the  stack 
and  I/O  ports.  Fortunately,  most  Forth-79 
implementations  are  also  supplemented 
with  these  and  other  useful  Fig-Forth 
words. 

The  Forth-79  version  of  WORD 
moves  text  strings  in  much  the  same  man¬ 
ner  as  the  Fig-Forth  version,  but  also 
leaves  a  pointer  to  the  leading  count  byte 
on  the  stack;  remove  HERE  from  both 
locations  in  the  definition  of  SAY”  and 
use  the  address  left  by  WORD  instead. 
Also,  the  initial  value  of  VOICE+PRINT 
should  not  precede  the  definition,  as 
Forth-79  variables  must  be  initialized 
after  being  defined.  Finally,  Forth-79 
does  not  explicitly  require  the  same  type 
of  return  stack  usage  as  Fig-Forth  (al¬ 
though  as  a  practical  matter,  few  Forth- 
79  systems  will  differ).  Some  experimen¬ 
tation  may  be  necessary  to  determine  if 
(SAY”)  will  operate  in  the  proper  manner. 

(Listing  begins  on  page  58) 
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SAY”  (Text  begins  on  page  55) 

Listing  One 


Screen  *  500 

0  (  Type'N  Talk  Output-1  CKM  06  Oct  82  ) 

1  HEX 

2 

3  *  CLEARTHROAT  (  initialize  Vector  Graphics  I/O  port) 

4  27  OCE  •lO  0  0  0  (  data  bytes) 

5  6  0  DO  7  P !  LOOP  (  output  6  bytes  to  port  7)  »  DECIMAL. 

6 

7  CLEARTHROAT  <  execute  to  initialize  port) 

8 

9  0  VARIABLE  VOICE+PRINT  (  0=voice  only,  l=say  and  print  too) 

10 

11  J  SAYCHARACTER  <  c  — >  ) 

12  BEGIN  7  F'(?  1  AND  UNTIL  (  wait  for  clear  to  send) 

13  DUP  6  P!  (  say  the  character) 

l't  VOICE+PRINT  G»  IF  EMIT  ELSE  DROP  THEN  (  print  if  desired)  5 

15  — > 

Screen  ♦  501 

0  (  Type'N  Talk  Output-2  CKM  06  Oct  82  ) 

1 

2  5  SPEAK  (  addr  n  >>  )  (  based  on  TYPE) 

3  -DUP  (  duplicate  non-zero  count  byte) 

4  IF  (  valid  count)  OVER  +  SWAP  (  find  loop  parameters) 

5  DO  I  C0  (  get  next  character) 

6  SAYCHARACTER  (  output  character)  LOOP 

7  ELSE  (  zero  count)  DROP 

8  THEN  ; 

9 

10  !  <SAY")  <  run-time  routine  based  on  (.") 

11  R  (  copy  pointer  to  next  word)  COUNT  DUP  (  get  byte  count) 

12  1+  R>  +  >R  (  increment  pointer  to  next  word) 

13  SPEAK  (  output  string)  i 

14 

15  — > 

Screen  *  502 

0  (  Type'N  Talk  Output-3  CKM  06  Oct  82  ) 

1 

2  DECIMAL 

3 

4  J  SAY"  <  immediate  word  based  on  . "  ) 

5  34  <  Ascii  of  "  delimiter) 

6  STATE  (?  (  fetch  compilation  state  flag) 

7  IF  (  compiling)  COMPILE  (SAY")  (  compile  run-time  pointer) 

8  WORD  (  move  string  to  top  of  dictionary) 

9  HERE  Cl?  (  fetch  count  byte)  1+  ALLOT  (  increment  dp) 

10  ELSE  (  executing)  WORD  (  move  string  to  top  of  dictionary) 

11  HERE!  COUNT  (  leave  address  &  count) 

12  SPEAK  <  output  string) 

13  THEN  J 

14  IMMEDIATE 

15  J  S 


Listing  Two 

Screen  #  503 

0  (  Type'N  Talk  screen  utilities  CKM  10  Oct  82  ) 

1  DECIMAL 

2 

3  J  SAYLINE  <  nl  ri2  »  )  <  based  on  .LINE) 

4  (LINE)  (  move  screen  n2  to  buffer,  leave  starting  addr  and) 

5  (  character  count  of  line) 

6  -TRAILING  (  adjust  count  for  trailing  blanks) 

7  SPEAK  (  output  the  line)  } 

8 
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LH  -Js  CO  r*o 


9  i  SAYSCREEN  (  n  >>  >  (  output  Ascii  text  of  entire  screen  n) 

10  SCR  !  <  save  screen  number  in  user  variable) 

11  16  0  DO  (  set  up  line  count  loop) 

I  SCF?  (?  (  leave  line,  screen  numbers) 

SAYLINE  (  say  the  line) 

LOOP  ; 


Screen  *  50*1 

0  (  Type'N  Talk  numeric  utilities  CKM  10  Oct  82  ) 

1  DECIMAL 

2  5  SAYD  (  d  »  )  (  based  on  D.) 

3  DUP  (  copy  high  bytes) 

■0  0<  IF  <  d  <  0  )  SAY"  NEGATIVE"  THEN  <  output  sign) 

5  DABS  <#  #S  #>  <  convert  to  Ascii,  leave  start  addr  and  ri) 

6  OVER  +  1+  SWAP  (  get  liMits  for  char,  by  char .  output  loop) 

7  DO  32  SAYCHARACTER  I  C@  SAYCHARACTER  32  SAYCHARACTER 

8  LOOP  <  output  with  blanks  between  characters)  » 

9 

10  S  SAYN  (  n  »  )  (  based  on  ,  ) 

11  S->D  (  convert  n  to  equivalent  d)  SAYD  (  output  d)  J 

12 

13  !  SAYU  (  u  »  )  (  based  on  U.) 

1*1  0  <  leave  a  dumny  high-order  half  of  d)  SAYD  <  output  d)  } 

15  ’,S 


End  Listings 
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A  TRS-80  8080  to 
Z80  Translator 


Back  in  the  May  1981  issue  of  DDJ, 
No.  45,  Robert  W.  Dea  offered  us  his 
program  “An  8080  to  Z80  Transla¬ 
tor  System.”  Following  is  a  description  of 
the  program  and  the  many  modifications 
I  have  made  to  it  that  will  allow  the  crea¬ 
tion  of  an  8080  source  file,  and  through 
translation,  will  produce  a  Z80  source  file 
that  will  be  accepted  by  Radio  Shack’s, 
or  any  equivalent,  editor/assembler. 

A  rather  large  project  I  had  been  con¬ 
sidering  for  some  time  was  to  convert  the 
Forth  Interest  Group’s  8080  version  of 
Forth  into  Z80  code.  Since  I  had  never 
bothered  to  learn  the  8080  mnemonics, 
and  was  well  versed  in  the  Z80  codes,  I 
thought  a  translated  version  would  after¬ 
ward  allow  easier  debugging  and  modifi¬ 
cation  of  the  Forth  program.  Since  my 
system  is  a  TRS-80,  48K,  model  I,  with 
a  single  disk,  I  had  to  modify  Mr.  Dea’s 
translation  program  to  work  with  Micro¬ 
soft’s  BASIC. 

The  program  was  also  modified  exten¬ 
sively  to  speed  up  the  translation  process. 
By  changing  his  READ  statements  into  a 
Data  Array,  and  by  using  a  binary  search, 
as  well  as  using  a  double-speed  modifica¬ 
tion  on  my  system,  and  also  compressing 


Anthony  T.  Scarpelli 


Anthony  T.  Scarpelli ,  98  Foxcroft  Drive, 
Scarborough,  ME  04074. 

This  program  is  based  on  Robert  W.  Dea’s 
original  8080  to  Z80  translator,  published 
in  DDJ  No.  45.  The  parts  of  his  original 
work  that  appear  here  are  used  with  his 
permission.  Mr.  Dea  has  now  placed  his 
original  translator  in  the  public  domain. 
Mr.  Scarpelli’s  work  here  is  also  in  the 
public  domain. 


the  BASIC  program  to  get  rid  of  spaces 
and  REM  statements,  I  was  able  to  sub¬ 
stantially  reduce  the  time  it  took  to  con¬ 
vert  the  8080  code  to  Z80  code.  For  in¬ 
stance,  using  a  test  file  of  8080  code  from 
POP  H  to  XTHL,  I  was  able  to  change  the 
translation  time  from  7  minutes  39  sec¬ 
onds  to  3  minutes  18  seconds. 

There  are  probably  many  other  mod¬ 
ifications  that  could  be  done  to  increase 
the  speed  even  further,  such  as  changing 
multiple  lines  to  single  lines,  watching 
how  all  the  variables  are  dimensioned, 
streamlining  loops,  etc.,  but  the  time 
to  do  this  didn’t  justify  the  few  seconds 
more  I  would  get.  So  I  left  it  the  way  it 
is  now,  and  it  works  fine. 

Many  parts  of  the  program  are  just  as 
Mr.  Dea  wrote  it,  but  I  added  comments 
in  some  lines  to  help  me  understand 
what’s  going  on  a  little  better,  and  I  also 
wrote  a  flow  chart  for  it.  I  found  my  first 
round  with  the  program  tough  going  be¬ 
cause  of  the  jumps  around  the  BASIC 
code,  but  now  my  understanding  is  a  little 
better,  and  I  have  included  the  flow  chart 
(starting  on  page  63)  so  that  you  can  more 
easily  modify  the  program  if  you  need  to. 

Let  me  go  through  the  program 
somewhat  to  show  you  what  I  did,  and  to 
indicate  how  an  editor/assembler  file  is 
created.  I  should  start  by  describing  the 
part  of  the  program  that  will  create  the 
8080  code  file,  so  jump  to  line  4810. 

Creating  the  8080  File 

I  use  Ultrados  for  my  operating  sys¬ 
tem,  so  the  first  thing  we  have  to  do  is 
make  sure  a  buffer  is  available;  that’s  the 
CMD“0”  in  line  4830.  With  TRSDOS 
you  don’t  have  need  of  this  code,  and  it 
can  be  deleted.  I  don’t  know  what  has  to 
be  done  with  other  DOSs. 


The  instructions  are  pretty  self- 
explanatory;  the  only  important  thing  I 
should  note  is  that  this  routine  does  no 
editing.  The  only  chance  to  correct  mis¬ 
takes  is  when  you  are  asked  “SURE?”. 
You  are  given  a  chance  to  change  your 
mind  by  inputting  an  “N.”  When  you  are 
rolling  along,  and  enter  a  lot  of  code, 
sometimes  you  forget  to  correct  mistakes. 
Generally  this  causes  no  harm;  the  trans¬ 
lation  will  just  ignore  an  opcode  that 
can’t  be  found,  or  something  weird  will 
be  added  to  the  translation.  This  can  be 
normally  edited  out  when  the  file  is  in 
the  editor/assembler. 

The  other  important  point  1  must 
mention  is  due  to  the  way  random  access 
files  are  written  to  disk.  Only  255  charac¬ 
ters  are  allowed  in  one  record,  but  there 
is  room  for  256.  The  256th  character  is 
a  random  character  of  some  type  in  the 
Z80  EDTASM  source  file  that  can  be 
edited  out  during  the  assembly  process.  It 
could  also  be  edited  out  from  disk  with  a 
zapper  program  of  some  type,  but  usually 
this  is  not  necessary.  When  using  the 
EDTASM  in  the  assembly  mode,  the 
assembly  process  can  be  switched  to  stop 
on  any  errors.  This  is  where  all  editing 
of  the  file  can  be  done.  Some  day  I’ll 
see  if  this  can  be  fixed.  As  you  can  see 
there  is  still  room  for  some  improve¬ 
ments  to  this  program. 

Line  5020  adds  an  up-arrow  (CHR$ 
(91))  delimiter  to  the  file’s  end  marker. 
All  entries  have  this  delimiter.  Lines  5030 
and  5040  open  the  random  access  file, 
and  set  up  AS  as  the  buffer. 

When  we  are  adding  8080  code  to 
the  file,  the  only  difference  between  a 
line  label  or  comment  line,  and  an  opera¬ 
tion  code  is  whether  there  is  a  space  in 
the  first  column  or  not.  Line  5070  prints 


— >  :  MEMORY  TEST 

ENTER  8080  FILE  NAME  ?  MEMTSTB0/TMP 

SURE? 

ENTER  Z80  DISK  FILESPEC  ?  MEMTSTZ/SOR 

\ 

ENTER  EDTASM  SOURCE  FILE  NAME  (6  CHAR.  MAX)  ?  MEMTST 

— >  MV I  C.01  ;LOAD  REPEAT  COUNTER 

START  LINE  NUMBERS  AT  ?  100 

SURE? 

\ 

-  00100  -  ;  MEMORY  TEST 

—  >  START  LX  I  SP.0FFFFH  : LOCATE  STACK  COUNTER 

00100  ;  MEMORY  TEST 

SURE? 

-  00110  -  MV I  C.01  : LOAD  REPEAT  COUNTER 

\ 

00110  LD  C.01  j  LOAD  REPEAT  COUNTER 

—  >  L  X  I 

-  00120  -  START  LX  I  SP.0FFFFH  ; LOCATE  STACK 

SURE?  N 

00120  START  LD  SP.0FFFFH  ; LOCATE  STACK 

\ 

-  00130  -  LX  I  H.0000H  ;LOAD  START  ADDRESS 

—  >  LX  I  H.0000H  ; LOAD  START  ADDRESS 

00130  LD  HL.0000H  :LOAD  START  ADDRESS 

SURE? 

-  00140  -  LX  I  D.1FFFH  ; LOAD  TOTAL  BYTES 

\ 

00140  LD  DE, 1FFFH  ; LOAD  TOTAL  BYTES 

—  > 

-  00 1 50  - 

Figure  1. 

Figure  2. 

Output  from  Create  routine. 

Output  from  Translate  program. 
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a  down-arrow  to  mark  this  column,  and 
line  5080  is  where  we  prompt  for  an  in¬ 
put.  See  Figure  1  for  an  example  of  this 
process.  Note  that  a  down-arrow  prints 
out  as  a  backslash  on  my  printer. 

If  you  were  to  exceed  the  25 5  charac¬ 
ter  input  to  a  record,  you  would  jump  out 
of  the  program  and  get  an  error  statement. 
To  avoid  this,  lines  5090  and  5100  make 
sure  that  you  are  aware  of  this  and  give  you 
a  chance  to  reduce  your  line  somewhat  to 
fit.  The  record  will  be  written  to  disk  as 
soon  as  it  exceeds  215  characters  and  is 
less  than  255.  This  wastes  a  few  bytes, 
but  is  simple  to  implement. 

The  rest  of  the  routine  takes  the  in¬ 
put  Al$,  adds  an  up-arrow,  and  adds  it 
to  A2$  if  the  length  is  right.  In  line  5200 
spaces  are  padded  to  A2$  and  it  is  placed 
into  buffer  A$.  Then  it  is  put  onto  disk  in 
line  5210.  The  record  number,  R,  is  incre¬ 
mented  and  we  can  now  jump  back  to 
add  more  8080  code  to  the  file.  An 
“@EXIT”  closes  the  file. 

Now  we  have  a  file  filled  with  8080 
code  and  comments  separated  by  an  up- 
arrow.  We  take  this  file  and  filter  it 
through  the  translator  in  the  next  section. 

Translating 

Figure  2  (page  60)  shows  output  from 
the  “translator”  part  of  the  program.  In  es¬ 
sence,  what  the  program  does  is  to  first  get 
the  8080  instruction,  search  through  an 
array  until  it  is  found  in  the  data,  and  then 
create  a  string  of  the  Z80  code.  Next,  the 
8080  operand  is  converted  to  equivalent 
Z80  code  as  specified  by  the  subfields  in 
the  rest  of  the  data  and  added  to  the  string. 
A  data  line  is  specified  in  lines  170-250. 

After  the  menu,  we  clear  string  space 
and  dimension  the  array  in  line  430.  The 
only  reason  for  line  440  is  to  make  sure 
the  speed  goes  back  to  normal  if  an  error 
occurs.  We  have  to  have  normal  speed 
during  disk  accesses.  This  error  trap  can 
be  expanded  if  necessary. 

Next  we  make  sure  two  buffers  are 
available  in  460,  then  comes  the  array  (83 
elements  long),  then  some  more  initiali¬ 
zation  until  line  1410.  Here  we  ask  for 
the  same  filespec  used  in  the  creation  of 
the  8080  source  code  file.  Then  we  get 
the  filespec  used  for  the  Z80  file,  and 
then  the  source  file  name,  which  is  re¬ 
quired  to  be  only  six  characters  long. 

The  format  of  an  editor/assembler 
file  is  as  follows:  the  first  character  is  a 
D3,  followed  by  six  ASCII  characters  for 
the  file  name.  If  the  name  is  less  than  six 
bytes,  the  rest  is  filled  up  with  spaces  to 
make  six.  Next  is  the  line  number,  five 
bytes  long,  with  each  decimal  number 
increased  by  176  decimal;  for  example,  a 
5  becomes  a  B5H  token.  Then  comes  a 
space,  and  then  the  text  with  a  termina¬ 
tor  of  an  0D.  The  next  line  number  fol¬ 
lows  immediately,  and  so  on.  The  final 
byte  of  the  file  is  a  1  A. 


Lines  1540  to  1590  fill  in  the  name 
with  spaces.  The  next  routine,  lines  1620 
to  1760,  produces  two  numbers  in  the 
form  of  strings;  one  is  C2$,  which  is  used 
for  printing,  and  the  other,  C3$,  is  for  the 
Z80  output  file. 

The  next  routine,  lines  1790  to  1880, 
goes  to  the  disk  and  gets  the  next  record, 
line  1810,  and  then  pulls  out  the  8080 
line  of  code.  Remember  it  is  delimited 
by  an  up -arrow,  CHR$(91).  It  leaves  this 
routine  with  the  code  in  1$,  which  is 
printed  on  the  screen. 

The  next  few  lines,  1910  to  1940, 
check  to  see  if  we  are  at  the  end  of  the 
8080  codes.  Also,  in  order  to  be  able  to 
merge  the  source  code  in  two  or  more 
editor/assembler  files,  it’s  a  good  idea  to 
note  the  last  line  number  so  that  you  can 
start  the  next  8080  file  with  a  larger  line 
number. 

We  have  two  output  buffers,  one  for 
printing,  02$,  and  one  that  will  go  to 
disk,  0$.  The  routine  in  lines  1980  to 
2000  first  checks  to  see  if  the  first  column 
is  a  semi-colon.  If  so,  it  will  just  add  the 
text  to  the  buffer.  If  not,  then  we  go  to 
the  subroutine  at  4030.  Since  this  is  an 
important  routine,  let’s  go  to  it. 

The  8080  code  line  is  delimited  by 
blanks.  If  the  first  column  is  a  blank  then 
we  know  that  the  line  contains  no  label, 
so  we  test  for  this  in  line  4040.  If  there  is 
a  character  we  read  through  1$  until  a 
blank  is  encountered.  The  label,  up  to  the 
next  blank,  is  edited  into  the  output  buf¬ 
fers  from  4060  to  4150.  Then  we  add 
eight  spaces  so  the  printout  of  02$  looks 
like  it  would  in  an  editor/assembler,  and 
then  add  a  tab  to  the  file  buffer  to  delimit 
it.  If  there  was  no  label,  then  we  merely 
skip  the  editing  part  of  the  routine.  Next 
we  jump  to  a  common  routine  that  scans 
the  code  line  (1$)  to  get  the  next  code 
out  of  it.  Let’s  jump  to  it  for  a  minute. 
GOSUB  3470. 

The  lines  from  3520  to  3590  just 
jump  over  any  blanks  in  the  code  line. 
Then  lines  3640  to  3760  accumulate  the 
actual  code  and  leave  it  in  N$.  Now  re¬ 
turn  to  4240,  and  return  to  2040.  Then 
GOSUB  4270.  A  lot  of  this  code  is  origi¬ 
nal  and  does  a  lot  of  jumping  around  as 
you  can  see.  It’s  not  my  style,  but  I 
didn’t  want  to  spend  a  lot  of  time  turning 
it  into  some  structured  code. 

Lines  4270  to  4350  are  the  binary 
search  routine  I  added.  It’s  a  typical  bi¬ 
nary  search  so  I  won’t  go  into  it.  The  rou¬ 
tine  exits  pointing  to  the  data  from  the  ar¬ 
ray  ready  to  be  worked  on.  That  is,  F  is  the 
index  into  the  array  DA$.  Now  we  can  re¬ 
turn  to  2110,  if  there  was  indeed  a  match. 

The  first  thing  we  do  is  to  make  sure 
our  output  buffers  are  empty.  Then  we  go 
back  to  our  subroutine  at  4030  that  merely 
looks  at  the  beginning  of  the  next  part  of 
the  8080  code  and  sees  a  blank.  Remember 
that  this  blank  separates  the  opcode  from 
its  operand.  We  then  skip  to  4170  where 


we  add  spaces  for  pretty  printing,  and  a 
tab  for  the  Z80  code.  Then  we  get  the 
next  subfield,  which  is  the  operand,  and 
put  it  in  N$.  Back  to  2150. 

Here  we  jump  immediately  to  4380, 
which  is  a  subroutine  that  puts  all  of  our 
array  data  into  another  small  array  Sl$(x). 
It  leaves  withX$  holding  the  Z80  code  and 
the  rest  of  the  array  filled  with  the  sub¬ 
fields  which  do  the  translation  of  the  oper¬ 
ands.  See  lines  90  to  250  for  a  review  of 
how  these  arrays  and  subfields  are  set  up. 

Now  back  to  2160  where  we  put  our 
Z80  code  into  the  buffers  and  add  spaces 
and  a  tab. 

The  next  job  is  to  read  the  subfield 
codes  so  that  the  rest  of  the  8080  code 
can  be  properly  added  to  the  buffers.  Our 
index  L  should  contain  the  number  of 
subfields  there  are.  We  start  a  loop  that 
reads  through  the  subfields  and  goes  to 
the  subroutine  that  produces  a  match. 
These  subroutines  are  relatively  simple. 


The  Subfield  Subroutines 

The  <A>  subroutine  is  the  longest 
and  most  of  the  others  jump  into  it,  so 
we’ll  start  our  journey  there  at  line  2800. 
The  first  thing  we  do  is  to  get  our  next 
subfield  from  the  8080  code.  Then  we 
initialize  H$  to  the  appropriate  tree  string 
and  start  to  search  the  string  for  a  match. 
The  search  routine  at  3820  is  simple 
enough,  so  1  won’t  dwell  on  its  finer  points. 

When  we  find  a  match  we  get  the  next 
subfield  definition  in  the  tree  string,  line 
2920  to  2990,  and  edit  it  into  the  buffers, 
line  3000.  We  set  our  match  flag  if  we 
hopefully  did  find  it. 

If  you  look  at  the  flowcharts  for  the 
rest  of  the  codes,  you  will  see  that  <G>, 
<B>,  <C>,  <D>,  and  <E>  all  jump 
into  the  <A>  subroutine,  and  that  <F> 
and  <S>  do  their  own  little  thing.  They 
are  simple  enough  not  to  explain  them  in 
detail. 

After  the  return  from  the  subrou¬ 
tines,  we  end  up  back  at  2370  and  then 
2410  on  a  good  match.  If  there  are  more 
subfields  to  translate,  we  loop  back  to  do 
the  rest.  We  finally  come  to  2430  where 
we  null  out  the  small  array,  and  then  edit 
anything  else  from  our  8080  code,  such 
as  comments,  into  our  buffers.  We  end  up 
at  2560  where  we  jump  to  2660. 


Get  It  Out 

The  routine  here  adds  in  our  line 
number,  prints  it  on  the  screen  at  2670, 
adds  a  carriage  return,  and  checks  to  see 
if  our  buffer  plus  the  output  buffer  is  less 
than  our  file  buffer.  If  the  buffer  would 
overflow,  it’s  time  to  put  it  onto  disk,  so 
we  jump  to  the  routine  at  4710  that 
does  just  that.  If  not,  we  add  the  code  to 
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the  output  buffer,  and  jump  back  to 
1650  where  we  increment  our  line  num¬ 
ber  and  start  the  whole  ball  rolling  again. 

As  you  can  see,  all  the  routines  are 
relatively  simple;  however,  because  of  all 
the  jumping  around,  it  is  difficult  to 
understand  and  follow  without  a  flow¬ 
chart.  This  is  a  good  reason  to  use  more 
structured  programming  methods. 

The  program  works,  though,  and  if 
you  need  to  get  those  old  8080  files  into 
Z80  code,  this  is  the  program  to  use. 

(Flow  charts  from  pages  63-67) 
(Listing  begins  on  page  68) 


(Continued  on  next  page) 
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GOSUB  3470 


<B>,<C>, 

<D>,<E> 

SIMILAR  TO  <G> 


GET  NEXT 
SUBFIELD 


SET  TO<G> 
DEFINE  TREE 


GOTO  2840 


ADD  TO  OUT 


PUT  BUFFER 


GOSUB  3470 


GET  NEXT 
SUBFIELD 


CHECK 

LENGTH,  ADD 
TO  BUFFER 


RETURN 


End  Flow  Chart 
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8080  to  Z80  Translator 

(Text  begins  on  page  60) 

10  '8080  TO  Z80  TRANSLATOR 

20  ’  FOR  USE  ON  TRS-80,  MODEL  I,  SINGLE  DISK  SYSTEM 

30  ’  USES  ULTRADOS  OPERATING  SYSTEM 

40  ’  CREATES  ZB0  SOURCE  FILE  FOR  EDITOR/ASSEMBLER 

50  ’  ORIGINAL  VERSION  BY  ROBERT  W.  DEA,  DDJ  MAY80  #45  P.48 

60  ’  MODIFIED  VERSION  BY  ANTHONY  T.  SCARPELLI .  JUNE  1982 

70  ’ 

80  ’ 

90  ’  THE  DATA  IN  THE  ARRAY  ARE  DEFINED  AS  FOLLOWS: 

100  ’  L. 8080MN. N. Z80MN. SUB1 . SUB2 _ 

110  ’  L  =  NUMBER  OF  CHARACTERS  IN  8080  MNEMONIC 

120  ’  9080MN  =  8080  INSTRUCTION 

130  '  N  =  NUMBER  OF  SUBFIELDS 

140  ’  Z80MN  =  Z80  EQUIVALENT  INSTRUCTION 

150  ’  SUBN  =  SUBFIELD  DEFINITIONS 

160  ’ 

170  '  THE  SUBFIELD  DEFINITIONS  ARE 

180  ’  <A>  -  REGULAR  ONE  TO  ONE  REGISTER  TRANSLATION 

190  '  <G>  —  RST  NUMBER  TRANSLATION 

200  '  <B>  —  REGISTER  PAIR  TRANSLATION 

210  ’  <C>  -  REGISTER  PAIR  TO  ACCUMULATOR 

220  ’  <D>  —  ACCUMULATOR  TO  REGISTER  PAIR 

230  '  <E>  -  EDIT  A  COMMA 

240  ’  <F>  -  EDIT  FOLLOWING  CHARACTER  STRING  TO  OUTPUT 

250  ’  <S>  -  ONE  TO  ONE  CHARACTER  STRING  TRANSLATION 

260  ’ 

270  ’ 

280  ’***  NOTE:  THIS  VERSION  USES  A  DOUBLE  SPEED  MODIFICATION 
290  *  OUT  254,1  CAUSES  DOUBLE  SPEED  CHANGEOVER 

300  ’  OUT  254,0  CAUSES  NORMAL  SPEED  CHANGEOVER 

310  ’ 

320  ’ 

330  CLS: PRINT"  ****  8080  TO  Z80  TRANSLATOR  ***»" 

340  PRINT : PR I NT “ENTER  ’C’  TO  CREATE  AN  8080  SOURCE  FILE" 

350  PR I NT " ENTER  *T'  TO  TRANSLATE  8080  TO  Z80  CODE  AND" 

360  PRINT"  CREATE  EDTASM  SOURCE  FILE" 

370  PR I NT "ENTER  ’X’  TO  EXIT  PROGRAM" 

380  INPUT  Q* 

390  IF  Q*="C"  THEN  4820 

400  IF  Q*="X"  THEN  OUT  254,0: END 

410  IF  Q*<>"T"  THEN  340 

420  ’ 

430  CLEAR  0: CLEAR  1500: DIM  DA* (83) 

440  ON  ERROR  GOTO  5320 

450  ’  MAKE  SURE  TWO  BUFFERS  ARE  AVAILABLE  (ULTRADOS) 

460  IF  PEEK ( &52 1 A ) < 2  THEN  CMD"0":G0T0  460 
470  ’ 

480  DA*  < 1 ) =“3. ACI .3. ADC. <F> . A, ,<S>" 

490  DA* (2) =  "3. ADC. 3. ADC. <F>. A, . <A>“ 

500  DA* (3) ="3. ADD. 3. ADD. <F>. A, . <A>" 

510  DA* (4) =“3. ADI .3. ADD. <F>.  A,  ,<S>“ 

520  DA*  <5) ="3. ANA. 1 . AND. < A>" 

530  DA*(6>=“3. ANI. l.AND.<S>" 

540  D A* ( 7 ) = " 4 . CALL . 1 . CALL .  < S > " 

550  DA*  (8)  =*"2.  CC.  3.  CALL.  <F>.  C,  .<S>" 

560  DA* (9)=" 2. CM. 3. CALL . <  F  > . M , .<S>" 

570  DA* ( 10) -"3. CMA. 0. CPL" 

580  DA* (11)= "3. CMC . 0 . CCF " 

590  DA* ( 12) =" 3. CMP .  1 . CP . <  A  > " 

600  DA* (13) ="3. CNC. 3. CALL. <F>. NC, . <S>" 

610  DA* ( 14) =  "3. CNZ. 3. CALL. <F>. NZ. .<S>" 

620  DA* ( 15) ="2. CP. 3. CALL.  <F>.P. . <S>“ 

630  DA* ( 16) ="3. CPE. 3. CALL. <F>. PE, . <S>“ 

640  DA*(17)="3. CPI. 1. CP. <S>“ 

650  DA* ( 18) ="3. CPO. 3. CALL. <F>. PO, . <S>" 

660  DA* (19)=" 2.CZ.3. CALL. <F>. Z , .<S>" 

670  DA* (20) ="3. DAA. 0. DAA" 

680  DA* (21 ) =”3. DAD. 3. ADD. <F>. HL, . <B>“ 

690  DA* (22) ="2. DB. 1 . DEFB. <S>" 

700  DA* (23) ="3. DCR. 1 . DEC. <A>" 

710  DA* (24) =“3. DCX. 1 . DEC.  <B>" 

720  DA*(25)="2.DI.0.DI" 

730  DA*  (26)  ="2.  DM.  l .  DEFM.  <S>"  (Continued  on  page  70) 
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8080  to  Z80  Translator 

(Listing  continued,  text  begins  on  page  60) 

740  DAS(27)="2.DW. l.DEFW.<S>" 

750  DA*(2B)="2.EI.0.EI" 

760  DA*  <  29 )  =  "  3  -  EQU .  1 .  EQU .  <  S  >  " 

770  DA* (30) ="3. HLT, 0. HALT" 

780  DA* (31)=" 2. IN. 5.  I N . < F > . A ,  (.<S>.<F>. >  .  “ 

790  DA* (32) ="3. INR.  1.  INC.<A>" 

800  DA* <33>=“3. INX. 1 . INC. <B>" 

810  DA* <34)="2.JC.3.JP. <F>.C, .<S>“ 

820  DA*<35>="2. JM.3. JP.<F>.M. -<S>" 

830  DA*<36>=”3. JMP. 1. JP.<S>" 

840  DA# (37) = “3. JNC. 3.JP.<F>. NC, .<S>" 

850  DA* (38) ="3.JNZ.3.JP.<F>.NZ, .<S>" 

860  DA*(39)="2. JP.3. JP.<F>.P. .<S>" 

870  DA*<40>="3. JPE.3. JP.<F>.PE, -<S>" 

880  DA*  <41 )  =  "3. JPO. 3. JP. <F>. PO, .<S>" 

890  DA* (42) ="2.JZ.3.JP.<F>. Z, . <S>“ 

900  DA*  ( 43 )  = 11 3 .  LDA  .  5  .  LD .  <  F  > .  A  ,  (.<S>.<F>.  )  " 
910  DA* (44) ="4. LDAX. 1 . LD. <D>" 

920  DA* (45) =" 4. LHLD. 5. LD. <F>. HL. (.<S>.<F>. ) " 
930  DA* (46) ="3. LX  1 . 3. LD. <B>. <E>. <S>" 

940  DA* (47) ="3. MOV. 3. LD. <A>.<E>.<A>" 

950  DA* (48) =“3. MVI . 3. LD. <A>. <E>. <S>" 

960  DA* (49)= "3- NOP . 0 . NOP " 

970  DA* (50) ="3- ORA. 1 . OR. <A>" 

980  DA* <51 > ="3. ORS. 1.0RG.<S>" 

990  DA* (52) ="3. ORI . 1 . OR. <S>“ 

1000  DA* (53) ="3. OUT. 5. OUT. <F>. <.<S>.<F>. ) ,  A" 
1010  DA*  (54)  =*'4.  PCHL.  2.  JP.  <F>.  (HL)  “ 

1020  DA*  ( 55 ) = " 3 .  POP .  1 .  POP .  <  B  > 11 
1030  DA* (56) =H 4. PUSH. l.PUSH.<B>" 

1040  DA*  <  57 )  =  "  3  . R AL . 0 . RLA " 

1050  DA*  ( 58 )  =  "  3 .  RAR .  0 .  RRA  “ 

1060  DA* (59) ="2. RC. 2. RET. <F>. C" 

1070  DA* (60)=" 3. RET. 0. RET" 

1080  DA*(61)="3.RLC.0.RLCA" 

1090  DA*  (62)  =*'2.  RM.  2.  RET.  <F>.  M“ 

1 100  DA* (63) ="3. RNC. 2. RET. <F>. NC" 

1110  DA* (64 ) =" 3. RNZ .2.  RET . <F>. NZ " 

1 120  DA* (65) ="2.  RP.  2.  RET. <F>. P" 

1 130  DA* (66) ="3. RPE. 2. RET. <F>. PE" 

1 140  DA* (67) ="3. RPO. 2. RET. <F>. PO" 

1150  DA*(68)="3.RRC.0.RRCA“ 

1160  DA* (69) ="3. RST. l.RST.<S>“ 

1170  DA* (70)= "2. RZ. 2. RET. <F>. Z" 

1 180  DA* (71 )="3. SBB. 3. SBC. <F>. A, . <A>" 

1190  DA* (72) ="3. SBI . 3. SBC. <F>. A, . <S>" 

1200  DA*  (73)  =‘‘4 .  SHLD.  5.  LD.  <F>.  <.<S>.<F>.  )  ,  HL" 
1210  DA* (74) ="4. SPHL. 2- LD. <F>. SP, HL" 

1220  DA* (75) ="3. ST A. 5. LD. <F>.  < . <S>. <F>.  )  .  A“ 
1230  DA*(76)="4.STAX.  l.LD.CCV 

1240  DA* (77) ="3. STC. 0. SCF” 

1250  DA* (78)=“ 3. SUB . 1 . SUB . <  A  > " 

1260  DA* (79)="3.SUI. l.SUB.<S>" 

1270  DA*<80)="4. XCHS.2.EX. <F>.DE.HL" 

1280  DA* (81) ="3.  XRA.  1 . XOR. <A>" 

1290  DA* (82) ="3. XRI  .  1 . XOR. <S>" 

1300  DA*<83)="4. XTHL.2.EX.<F>. <SP>,HL" 

1310  ’ 

1320  ’  INITIALIZE  SYNTAX  TREE  STRINGS 

1330  A3*="A  ABBCCDDEEHHLLM  (HL)“ 

1340  B*="PSW  AF  B  BC  D  DE  H  HL  SP  SP" 

1350  C*="B  (BC),A  D  (DE),A“ 

1360  D*= " B  A, (BC)  D  A, (DE) " 

1370  E*="  ,  , " 

1380  G*="0  0182  10H  3  18H  4  20H  5  28H  6  30H 
7  38H" 

1390  ’ 

1400  ’  CREATE  FILE  NAMES  AND  BUFFERS 
1410  PRINT: INPUT "ENTER  8080  FILE  NAME  ";I9* 
1420  OUT  254,0:  ’NORMAL  SPEED 

1430  OPEN  "R" , 1 , 19* 

1440  FIELD  1,  255  AS  A* 

1450  I NPUT " ENTER  Z80  DISK  FILESPEC  " ; F9* 
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1460  INPUT"ENTER  EDTASM  SOURCE  FILE  NAME  (6  CHAR.  MAX)  " ; 09* 
1470  IF  LEN(09*>>6  THEN  PRINT"**  TOO  LONG  **":GOTO  1460 
1480  OPEN  "R",2,F9* 

1490  FIELD  2,  255  AS  Z* 

1500  OUT  254, 1  '  ***  DOUBLE  SPEED 

1510  R=1:F1=1:W=1:C9=0 
1520  ’ 

1530  ’  FILL  IN  FILE  NAME  WITH  SPACES  IF  NECESSARY 
1540  K=LEN<09*> 

1550  IF  K=6  THEN  1590 
1560  FOR  I=K  TO  5 
1570  09*=09*+“  " 

1580  NEXT  I 

1590  D1*=CHR* (21 1 > +09* 

1600  ' 

1610  ’  GENERATE  AUTO  LINE  NUMBERING  &  INC  BY  10 
1620  INPUT "START  LINE  NUMBERS  AT  ";C0: PRINT 
1630  C0=C0-10:C1=900000+C0 
1640  ’  INC  LINE  COUNT  BY  10 
1650  C1=C1+10: C3*="" 

1660  ’  CONVERT  TO  ASCII  NUMBER  5  PLACES 
1670  C 1 *=STR* (Cl) 

1680  C1*=RIGHT*(C1*,5>+"  " 

1690  '  CONVERT  TO  TOKENS 
1700  FOR  1=1  TO  5 

1710  C4*=CHR* (VAL (MID* (Cl*,  1,1) )+176) 

1720  C3*=C3*+C4* 

1730  NEXT  I 
1740  C2*=C1* 

1750  C3*=C3*+"  " 

1760  PRINT"-  ";C2*+"  -  "; 

1770  ’ 

1780  ’  GET  NEXT  8080  INSTRUCTION 
1790  Z1*=CHR*(91> 

1800  R 1 *= " " 

1810  IF  F 1 >C9  THEN  4510 
1820  R1*=R1*+MID*(R*,F1, 1) 

1830  IF  RIGHT *(R1*, 1)=Z1*  THEN  1860 
1840  F 1  =F  1  +  1 
1850  GOTO  1810 
1860  F 1=F 1+1 

1870  I*=LEFT*(R1*,LEN(R1*)-1) 

1880  PRINT  I* 

1890  ' 

1900  ’  DO  WE  HAVE  END  OF  TRANSLATION? 

1910  IF  I*< V3EXIT"  THEN  1980 

1920  PRINT: PRINT" IF  NOT  END  OF  LISTING  NOTE  LINE  NUMBER." 

1930  INPUT "PRESS  < ENTER >  TO  CLOSE  FILE  AND  RETURN  TO  MENU";X* 
1940  GOTO  4620 
1950  ’ 

1960  '  EDIT  LINE#  IN  AND  CONVERT  TO  Z80  INSTRUCTION 
1970  ’  CHECK  FOR  JUST  COMMENT  LINE 
1980  IF  LEFT* (I*, 1><>“; "THEN  2010 
1990  0*=0*+ I *: Q2*=02*+ I * 

2000  GOTO  2660 
2010  GOSUB  4030 
2020  ' 

2030  ’  DO  WE  HAVE  AN  8080  INSTRUCTION  IN  INSTRUCTION  BUFFER'7 

2040  IF  LEN(N*)=0  THEN  2660 

2050  ’  YES'  NOW  SEARCH  FOR  MATCH 

2060  GOSUB  4270 

2070  ’ 

2080  ’  THERE  WAS  A  MATCH,  Z8*=8080  CODE 
2090  ’  GET  NEXT  STRING 
2100  '  INIT  OUTPUT  STRING  BUFFER 
2110  0*="“:02*="" 

2120  GOSUB  4030 
2130  ' 

2140  ’  NOW  GET  Z80  OUTPUT  INSTR  AND  EDIT  TO  OUTPUT  BUFFERS 

2150  GOSUB  4380 

2160  0*=0*+X*:02*=02*+X* 

2170  FOR  K=LEN ( 02*  >  + 1  TO  16 
2180  02*=02*+"  " 

2190  NEXT  K 

2200  0*=0*+CHR* (09) 

2210  ’ 

2220  ’  NOW  READ  TRANSLATION  SUBFIELDS 

2230  IF  L=0  THEN  2430  (Continued  on  next  page) 
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8080  to  Z80  Translator 

(Listing  continued,  text  begins  on  page  60) 


2240 

2250 

2260 

2270 

2280 

2290 

2300 

2310 

2320 

2330 

2340 

2350 

2360 

2370 

2380 

2390 

2400 

2410 

2420 

2430 

2440 

2450 

2460 

2470 

2480 

2490 

2500 

2510 

2520 

2530 

2540 

2550 

2560 

2570 

2580 

2590 

2600 

2610 

2620 

2630 

2640 

2650 

2660 

2670 

2680 

2690 

2700 

2710 

2720 

2730 

2740 

2750 

2760 

2770 


2780 

2790 

2800 

2810 

2820 

2830 

2840 

2850 

2860 

2870 

2880 

2890 

2900 

2910 

2920 

2930 

2940 

2950 

2960 


FOR  1=2  TO  L+l 
S*=S1*<I> 

’  CHECK  SUBSET  FOR  DEFINITION  MATCH  AND  TRANSFER  TO 
’  DEFINITION  PROCESS  SECTION. 

IF  S*="<A>"  THEN  GOSUB  2800 
THEN  GOSUB  3100 
THEN  GOSUB  3150 
THEN  GOSUB  3190 
THEN  GOSUB  3230 
THEN  GOSUB  3270 
THEN  GOSUB  3310 
THEN  GOSUB  3390 


IF  S*=''<G> 

IF  S*="<B> 

IF  S*="<C> 

IF  S*="<D> 

IF  S*="<E> 

IF  S*=H<F> 

IF  S*='*<S> 

’  IS  MATCH  FLAG  SET? 

IF  F=1  THEN  2410 
’  WE  GET  HERE  IF  PARSE  FAILED 
GOTO  2110 

’  YES  WE  HAVE  A  GOOD  TRANSLATION 
NEXT  Is  IF  F<  >1  THEN  2110 
’  ZERO  ARRAY 

FOR  1=1  TO  6: SI*  < I ) =“ “ : NEXT  I 
’  EDIT  ANYTHING  THATS  LEFT 
IF  T+1>LEN<I*>  THEN  2560 
FOR  K=LEN <02*>+l  TO  29 
02*=02*+"  " 


NEXT  K 

0*=0*+CHR*  <  09 ) +CHR*  <  09 ) 

FOR  K=1  TO  LEN (I*) 

T 1 *=M I D* <  I  * ,  K , 1) 

IF  T 1  *=  *' ;  "  THEN  GOTO  2540 
NEXT  K 

0*=0*+R I GHT* (I*. LEN  < I* ) — K+l > 
02*=02*+R I GHT* (I*, LEN  < I  * ) -K+ 1 > 
GOTO  2660 


’  NO  FIND  EXIT 
02*="*N0  MATCH*  “+I* 

’  OUTPUT  *NO  MATCH*  MSG  AND  DEC  LINE  COUNTER  BY  10 
PRINT  02* 

C1=C1-10 
0*=••',  :GOTO  2690 

’  EDIT  LINE#  IN  AND  OUTPUT  THE  TRANSLATED  Z80  INST 
0*=C3*+0* 

PRINT  Cl *+02* 

0*=0*+CHR*<13) 

L9=LEN <01 *>  +LEN (0*) 

IF  L9<255  THEN  2750 
L8=255-LEN<01*> 

01*=01*+LEFT*  <0*,L8> 

0*=R I GHT*  <  O* , LEN  <  O*  > -L8 ) 

GOTO  4710 
Ol*=01*+0* 

0*=" " : 02*= " “ 

GOTO  1650 


’  PROCESS  SINGLE  REG  SECTION  "<A>" 

GOSUB  3470 

’  IN IT  PROCESS  SECTION  AND  SET  TO  <A>  TREE 
H*=A3* 

’  INIT  TREE  SEARCH  SECTION 
H2=0: T2= 1 

’  CHECK  IF  WE  PARSED  THE  WHOLE  INPUT  8080  INST  YET. 

’  SEE  IF  IT  SATISFIES  THE  8080  DEFINITION 
IF  T2>LEN<H*>  THEN  3050 

’  GO  SCAN  THE  DEFINITION  TREE  FROM  LEFT  TO  RIGHT  TO 
’  GET  NEXT  SUB  DEFINITION 
GOSUB  3820 

’  DOES  IT  MATCH  THE  SUB  ELEMENT  WE  HAVE? 

IF  M*=N*  THEN  2990 

’  NO  IT  DOES  NOT,  SO  SKIP  THE  NEXT  Z80  SUB  TRANSLATION 
’  AND  GO  TRY  FOR  ANOTHER  8080  SUB  DEFINITION  MATCH. 
GOSUB  3820 
GOTO  2870 
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2970  ’  WE  HAVE  AN  8080  SUB  DEFINITION  MATCH.  NOW  GET  THE 
2980  ’  Z80  TRANSLATION  AND  EDIT  IT  INTO  THE  OUTPUT  BUFFER  0*. 

2990  GOSUB  3820 
3000  0*=0*+M*: 02*=02*+M* 

3010  ’  SET  MATCH  FLAG 
3020  F=1 
3030  RETURN 

3040  '  SET  NO  MATCH  FLAG 
3050  F=0 
3060  RETURN 
3070  ’ 

3080  ’  PROCESS  " <  G  > “  DEFINITIONS 
3090  '  GET  NEXT  INPUT  SUB  FIELD 
3100  GOSUB  3470 

3110  ’  SET  TO  <G>  DEFINITION  TREE 
3120  H*=G* 

3130  GOTO  2840 

3140  ’  PROCESS  “<B>"  DEF 

3150  GOSUB  3470 

3160  H*=B* 

3170  GOTO  2840 

3180  ’  PROCESS  “ <  C  > "  DEF 

3190  GOSUB  3470 

3200  H*=C* 

3210  GOTO  2840 

3220  ’  PROCESS  “<D>“  DEF 

3230  GOSUB  3470 

3240  H*=D* 

3250  GOTO  2840 

3260  '  PROCESS  "<E>"  DEF 

3270  GOSUB  3470 

3280  H*=E* 

3290  GOTO  2840 

3300  ’  PROCESS  “<F>"  DEF 

3310  X*=S1*(I+1> 

3320  ’  JUST  EDIT  NEXT  Z80  TRANS  ELEMENT  TO  OUTPUT  BUFFER 
3330  0*=0*+X*: 02*=02*+X* 

3340  ’  SET  MATCH  FLAG 
3350  F=1 
3360  1=1+1 
3370  RETURN 

3380  ’  PROCESS  "<S>"  DEF 
3390  GOSUB  3470 
3400  F=1 

3410  IF  LENIN*) =0  THEN  F=0 
3420  0*=0*+N*:02*=02*+N* 

3430  RETURN 
3440  ' 

3450  '  SCANNER  RETURNS  N* 

3460  ’  I NIT  SUB  FIELD  SCANNER  SECTION 
3470  H=T+1 
3480  N*="“ 

3490  H1=H 

3500  ’  SCAN  FOR  NEXT  8080  SUB  FIELD  STARTING  WITH  FIRST 
3510  ’  NON-BLANK. 

3520  FOR  J=H1  TO  LENII*) 

3530  ’  GET  NEXT  CHAR 

3540  ’  IS  IT  A  BLANK? 

3550  IF  MID*II*. J, 1><>“  "  THEN  J=LEN < I*) s GOTO  3590 

3560  ’  YES!  GO  GET  NEXT  CHAR 

3570  H=H+1 

3580  T=T+1 

3590  NEXT  J 

3600  ’  WE  SHOULD  BE  POINTING  TO  START  OF  8080  SUB  FIELD 
3610  H1=H 

3620  ’  SCAN  UNTIL  WE  GET  A  TERMINATOR  OR  END  OF  LINE. 

3630  ’  ("BLANK"  AND  " , "  ARE  TERMINATORS) 

3640  FOR  J=H1  TO  LENII*) 

3650  ’  GET  NEXT  CHAR 

3660  ’  IS  IT  A  BLANK? 

3670  IF  MID* (I*,J, 1)=“  "  THEN  GOTO  3790 
3680  ’  IS  IT  A 

3690  IF  MID* 1 1*, J, 1)=“ . “  THEN  GOTO  3770 

3700  '  NO!  ITS  NONE  OF  THE  ABOVE  SO  EDIT  THIS  CHAR  INTO 

3710  *  INSTRUCTION  BUFFER. 

3720  N*=N*+M I D* 1 1 * , J , 1) 

3730  T=T+1 

3740  '  GO  GET  NEXT  CHAR  (Continued  on  next  page) 
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8080  to  Z80  Translator 

(Listing  continued,  text  begins  on  page  60) 

3750  NEXT  J 
3760  RETURN 

3770  IF  LEN  <  NS >  =0  THEN  T=T+1 
3780  IF  LEN (NS) =0  THEN  NS=“," 

3790  RETURN 
3800  ’ 

3810  ’  SCAN  THE  TREES 
3820  H2=T2 
3830  MS="“ 

3840  H3=H2 

3850  FOR  J=H3  TO  LEN  <  HS  > 

3860  ’  TAB  TO  NEXT  NON-BLANK  CHAR 

3870  IF  MIDS(HS,  J,  1)0"  "THEN  J=LEN (HS) : GOTO  3900 

3880  H2=H2+1 

3890  T2=T2+1 

3900  NEXT  J 

3910  H3=H2 

3920  ’  GET  NEXT  SUB  DEF  OF  8080  INSTRUC. 

3930  FOR  J=H3  TO  LEN CHS) 

3940  ’  HAVE  WE  A  BLANK  YET? 

3950  IF  MIDS(HS. J, 1>="  "  THEN  J=LEN (HS) : GOTO  3990 
3960  ’  NO1  THEN  ADD  THIS  CHAR 

3970  MS=MS+M I DS ( HS , J , 1 ) 

3980  T2=T2+1 

3990  NEXT  J 
4000  RETURN 
4010  ' 

4020  ’  SECTION  TO  EDIT  A  LABEL  AND  OUTPUT  Z80  TRANSLATION 
4030  H=0:T=1 

4040  ’  IS  THERE  A  CHAR  IN  C0L#1? 

4050  IF  LEFTS(IS, 1)=“  "  THEN  4170 
4060  H=1 

4070  FOR  K=1  TO  LEN (I*) 

4080  ’  GET  NEXT  CHAR 

4090  ’  IS  IT  A  BLANK 

4100  IF  MIDS(IS,K, 1>="  "  THEN  K=LEN ( I*) : GOTO  4150 
4110  ’  NO!  NOT  A  BLANK  THEN  MUST  BE  PART  OF  LABEL  FIELD. 

4120  ’  SO  EDIT  IT  INTO  OUTPUT  BUFFER 

4130  OS=OS+MIDS(IS,K, 1) : 02S=02S+MIDS ( IS, K, 1) 

4140  T=K+1 

4150  NEXT  K 

4160  ’  TAB  TO  COL  8  FOR  PRINTOUT 
4170  FOR  K=LEN(02S>+1  TO  8 
4180  02S=02S+“  " 

4190  NEXT  K 

4200  ’  INSERT  TAB  INTO  OUTPUT  BUFFER 
4210  OS=OS+CHRS(09) 

4220  *  NOW  SCAN  FOR  THE  8080  INSTRUC. 

4230  GOSUB  3470 
4240  RETURN 
4250  ’ 

4260  ’  BINARY  SEARCH  THROUGH  DATA  STATEMENTS  FOR  MATCH 
4270  U=83:L=1 

4280  F=INT< (L+U) /2>  *  CALCULATE  FENCE 

4290  N=VAL (LEFTS (DAS <F>  ,  1) ) : Z8S=MIDS (DAS (F) ,3,N> 

4300  IF  Z8S=NS  THEN  RETURN 
4310  IF  L>=U  THEN  2590 
4320  IF  Z8S >NS  THEN  4340 
4330  L=F+1 : GOTO  4280 
4340  U=F— 1 : GOTO  4280 
4350  GOTO  2590  ’  NO  MATCH 

4360  ’ 

4370  ’  SUBROUTINE  TO  READ  THROUGH  ARRAY  DATA 
4380  L=VAL ( LEFTS ( DAS ( F ) , 1 ) ) : N 1 =L+4 
4390  L=VAL(MIDS(DAS(F) ,N1, 1) > 

4400  FOR  1=1  TO  L+l 
4410  FOR  J=1  TO  6 
4420  S1S=MIDS(DAS(F) ,N1+1+J, 1) 

4430  IF  S1S="."  THEN  N1=N1+J: J=6: GOTO  4450 

4440  S1S(I)=S1S(I)+S1S 

4450  NEXT  J 

4460  NEXT  I 

4470  XS=S1S(1) 
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4480  RETURN 
4490  * 

4500  ’  GET  RECORD  FROM  DISC 
4510  R*="  '• 

4520  OUT  254,0 
4530  GET  1 , R 
4540  R$=A* 

4550  Fl=l 
4560  R=R+1 
4570  C9=LEN(R*> 

4580  OUT  254 ,1  ’  *  *  *  DOUBLE  SPEED 

4590  GOTO  1800 
4600  ' 


4610  ’  CLOSE  FILES 

4620  IF  LEN(O1*><0  THEN  OUT  254,0: GOTO  4670 
4630  01*=01*-t-CHR*  (26) 

4640  LSET  Z*=01* 

4650  OUT  254,0 
4660  PUT  2, W 
4670  CLOSE  1: CLOSE  2 
4680  GOTO  330 
4690  ’ 

4700  ’  PUT  RECORD  ONTO  DISC 
4710  LSET  Z*=01* 

4720  OUT  254,0 
4730  PUT  2,W 
4740  W=W+1 
4750  01*="" 

4760  ’OUT  254,1 
4770  GOTO  2750 
4780  ’ 

4790  ’ 

4800  ’ 

4810  ’  SECTION  TO  CREATE  AN  8080  SOURCE  FILE 
4820  ’ 

4830  CLEAR  0: CLEAR  1500: CMD"0"  ’  MAKE  SURE  BUFFER  AVAILABLE 
4840  R=1 : A*=" “ 

4850  ’ 

4860  CLS: PRINT"  *  8080  CREATE  PROGRAM  *" 

4870  PRINT 

4880  PR I NT "TYPE  8080  SOURCE  IN  FOLLOWING  FORMAT:" 

4890  PRINT"  LABEL  -  OPERATION  -  OPERAND  -  COMMENT" 

4900  PRINT"  EXAMPLE:  START  LX  I  H,0001H  ; LOAD  ADDRESS 
4910  PRINT"  XRA  A  ; CLEAR  A  REGISTER" 

4920  PRINT"  ONLY  ONE  SPACE  IS  REQUIRED  BETWEEN  ENTRIES." 
4930  PR I NT "A  LABEL  OR  LEADING  SHOULD  NOT  START  WITH" 

4940  PRINT"  A  SPACE,  AN  OPERATION  SHOULD." 

4950  PR I NT "AN  ’N’  AFTER  THE  ’SURE’  WILL  CANCEL  ENTRY," 

4960  PRINT"  AN  < ENTER >  ADDS  ENTRY  TO  FILE." 

4970  PR I NT "TYPE  ’ SEX  IT’  TO  EXIT  TO  MENU." 

4980  PR I NT "A  BUFFER  FROM  215  TO  255  CHARACTERS  LONG  IS" 

4990  PRINT"  SAVED  TO  DISK. " 

5000  PRINT: INPUT "ENTER  8080  OUTPUT  FILE  NAME  “ ; R* 

5010  PRINT-OUTPUT  FILE  ’".R*.”’  IS  ON  DRIVE  #0" 

5020  A3*="3EXIT"+CHR*(91> 

5030  OPEN  "R",1,R* 

5040  FIELD  1,255  AS  A* 

5050  PRINT 
5060  X*="" 

5070  PRINT"  ";CHR*(92> 

5080  LINE  INPUT" — >  ";  Al* 

5090  B=LEN(A1*)+1:C=LEN(A2*> 

5100  IF  B+C>255  THEN  PRINT"NEXT  ENTRY  WILL  EXCEED 
BUFFER  SPACE  AND  PRODUCE  ERROR!!  SAY  ’N’! 

YOU  HAVE  ONLY" ; 255— LEN  <A2*> ; “  CHARACTERS  LEFT!" 

5110  I NPUT " SURE " ; X  * 

5120  IF  X*=“N"  THEN  5060 
5130  A1*=A1*+CHR* (91 ) 

5140  A=LEN(A2*> 

5150  IF  A >2 15  THEN  5190 
5160  A2*=A2*+A1* 

5170  IF  A1*=A3S  THEN  5200 
5180  GOTO  5060 

5190  IF  LEN(A1*><1  THEN  5240 
5200  LSET  A*=A2* 

5210  PUT  1 , R 
5220  R=R+1 


5230  IF  A1*=A3S  THEN  5270  ELSE  5250 
5240  A1S="" 


(Continued  at  right,  top  of  page) 


5250  A2*=A1* 

5260  GOTO  5060 
5270  CLOSE  1 
5280  GOTO  330 
5290  END 
5300  ’ 

5310  ’  ERROR  TRAP 
5320  OUT  254,0 
5330  RESUME 
5340  ’ 

5350  ’  END  OF  PROGRAM 


End  Listing 
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by  D.  E.  Cortesi 


Disk  Drives  Us  Crazy 

In  February  we  presented  Loren 
Amelang’s  request  for  explanations  why 
perfectly  good  diskettes  could  come  up 
with  read  errors  after  being  stored  for  a 
while.  David  Oster  (whose  letterhead  pro¬ 
claims  The  People’s  Republic  of  Santa 
Monica,  its  motto  “Unity  and  Breakfast 
for  All”)  suggests  two  ways.  First,  he 
points  out,  drives  vary  with  time.  “Apple 
drives,  in  particular,  seem  to  need  fre¬ 
quent  realignment.  The  disks  you  read 
and  write  every  day  change  with  the  drive, 
but  the  drive  changes  enough  that  stored 
disks  stop  working.” 

Amelang  also  wondered  why  one 
program  could  always  read  the  bad  disk¬ 
ettes  when  others  couldn’t.  Oster  has  a 
comment  on  this,  too. 

“When  I  had  this  problem  it  turned 
out  that  the  programs  were  accessing  the 
disk  in  very  different  ways.  When  the 
program  that  failed  wanted  to  go  to  an 
inner  track  like  track  70,  it  would  tell  the 
controller  “go  to  track  70.”  When  the 
program  that  worked  wanted  to  go  there, 
it  told  the  controller  “go  to  the  next 
track,”  70  times.  If  you  tell  a  disk  con¬ 
troller  to  step  once,  it  just  does  it.  If 
you  tell  it  to  seek  a  long  way,  it  runs  an 
internal  subroutine  that  does  a  fancy 
acceleration-deceleration  of  the  head 
carriage.  Only  when  it  gets  there  does  it 
begin  looking  for  a  track.  If  the  disk  is  a 
slightly  different  shape  than  the  control¬ 
ler  expects,  the  position  error  in  going  70 
tracks  is  70  times  as  large  as  the  position 
error  from  stepping  one  track. 

“I  had  this  problem  because  my  drives 
weren’t  properly  cooled.  There  was  a 
nice  big  fan  in  the  cabinet,  but  there  were 
a  couple  of  unused  connector  holes  and 
all  the  air  flowed  through  them  and  not 
enough  of  it  flowed  over  the  electronics. 
I  replaced  a  few  heat-damaged  chips, 
covered  the  extra  holes  with  tape,  and 
haven’t  had  a  problem  since.” 

OK,  those  are  reasonable  propositions 
(especially  the  part  about  air  flow),  but 
they  sound  to  us  as  if  they  would  be 
hard  ware -specific.  For  example,  accord¬ 
ing  to  its  data  sheets,  the  Western  Digital 
FD1793  controller  (used  in  the  popular 
California  Computer  Systems  2422  board) 
performs  a  seek  from  track  zero  to  track 
70  by  doing  70  “step-in”  operations. 
And  the  1793  doesn’t  make  any  adjust¬ 
ments  on  the  resulting  position;  it  just 
assumes  that  a  step  is  a  step. 

There  must  be  a  lot  more  things  that 
could  be  said  about  Loren  Amelang’s 


problem.  Another  open  problem  is  that  of 
Ernest  Knipp,  whose  Z80 system  occasion¬ 
ally  goes  catatonic.  We  look  forward  to 
more  contributions  on  both  these  topics. 

Counts  and  Measures 

In  that  February  issue,  we  gave  Burks 
Smith  room  to  speak  out  on  the  use  of 
floating-point  arithmetic,  and  its  lack  of 
precision  as  usually  implemented.  The 
heart  of  his  presentation  may  have  been 
his  statement  that  “If  something  called 
‘double-precision  arithmetic’  can’t  take 
ten  percent  of  a  dollar  and  get  exactly  ten 
cents,  there  shouldn’t  be  any  excuses. 
The  answer  is  just  plain  wrong!”  Oster 
has  a  comment  on  that. 

“Smith  has  confused  counts  with 
measures.  When  you  say  you  have  ten 
dollars,  you  are  saying  you  have  1,000 
pennies  —  a  count.  When  you  say  you 
have  ten  gallons  of  water,  you  are  not 
saying  that  you  have  a  certain  number  of 
water  molecules,  but  making  a  statement 
about  a  physical  quantity  that  you  only 
know  to  a  certain  precision  —  a  measure. 
Floating-point  numbers  were  designed 
for  calculation  with  measures;  integers 
were  designed  for  calculation  with  counts. 

“So,  if  something  called  ‘double¬ 
precision  arithmetic’  takes  ten  percent  of 
a  dollar,  it  is  right  as  long  as  its  answer 
lies  between  0.999 ...  9  and  1 .000 .  .  .01. 
It  may  not  be  what  you  want,  but  it  is 
what  that  arithmetic  is  designed  to  do. 
There  are  some  experimental  computer 
languages  where  all  numbers  input  to  a 
program  must  be  labeled  with  whether 
they  are  measures  or  counts,  and  if  mea¬ 
sures,  how  accurate  they  are  and  what 
units  they  are  in.  The  results  of  the  pro¬ 
gram  are  automatically  expressed  in 
appropriate  units  and  you  are  told  how 
precise  the  results  are.” 

Distinguishing  “counts”  and  “mea¬ 
sures”  certainly  helps  clarify  the  problem 
in  our  mind,  at  least.  On  reflection,  it 
seems  that  the  distinction  we  try  to  draw 
between  “commercial”  and  “scientific” 
applications  is  based  on  which  kind  of 
numbers  is  preponderant  in  each.  What 
we  call  “commercial”  work  deals  mostly 
with  counts;  “scientific”  computing  deals 
mostly  with  measures.  Think  about  it. 

But  there  is  more  to  be  said  on  this 
topic  as  well,  and  your  contribution  is 
still  welcome.  We  asked  other  questions 
in  that  February  column.  CBASIC  uses  a 
BCD  representation  for  float  numbers  that 
has  about  the  same  precision  as  MBASIC’s 
binary  one  —  has  anyone  really  compared 
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the  results  of  the  two  on  the  same  prob¬ 
lem  set?  We  also  wondered  if  there  were 
any  ratios  that  have  a  finite  representa¬ 
tion  in  binary  but  not  in  decimal  (as  there 
are  decimal  fractions  that  can’t  be  repre¬ 
sented  in  binary).  Oster’s  answer  is  “no”; 
can  you  figure  out  what  leads  him  to  this 
conclusion? 

Spotting  DDT 

Back  in  October  of  1 982,  we  showed 
one  way  to  get  DDT  to  load  in  such  a 
way  that  the  resident  parts  of  CP/M  were 
still  visible  and  the  CCP  wasn’t  overlaid. 
Aubrey  Hutchison  has  another  way.  If 
you  know  where  you  want  DDT  to  load 
itself,  the  most  direct  way  is  to  alter  its 
code.  Use  DDT  to  modify  DDT.COM. 
Look  at  the  instructions  around  0150h; 
you  should  find 

0150  SUB  B 

0151  MOV  D,A 

If  you  replace  those  two  instructions  with 
the  single  instruction 

0150  M VI  D,xx 

you  will  have  a  version  of  DDT  that  will 
always  load  itself  at  x.vOOh  in  storage. 

Fun  With  Your  New  BIOS 

We’re  working  at  bringing  up  CP/M  3 
(or  “CP/M  Plus,”  as  Digital  Research 
wants  to  call  it)  on  our  own  system.  The 
first  step  is  to  get  the  present  BIOS  to 
assemble  with  a  relocating  assembler. 
We’re  using  RMAC  and  LINK80  from 
Digital  Research,  mostly  because  RMAC 
allows  the  long,  long  labels  that  we  like  to 
use. 

Rather  than  do  a  whole  lot  of  new 
code,  then  debug  it  while  learning  a  new 
operating  system,  we  thought  we  would 
first  make  the  new  BIOS  work  with  CP/M 
2.2.  Then  we’d  enhance  it,  still  on  2.2, 
and  finally  make  the  few  changes  needed 
for  CP/M  3.  One  of  the  enhancements  we 
want  to  make  while  still  running  the  old 
operating  system  is  to  split  the  BIOS  into 
a  fixed  part  and  a  banked  part.  The  more 
complicated  disk  functions  go  into  the 
banked  BIOS;  the  serial  I/O  and  the  trivial 
disk  functions  like  “set  track”  remain  in 
the  fixed  part. 

With  the  complicated  functions  set 
aside  in  banked  storage,  we  can  really  let 
them  spread  out  and  get  competent.  For 
example,  we  plan  to  display  disk  error 
messages  in  detail,  in  English.  That’s 
something  there  just  isn’t  room  for  when 
the  whole  BIOS  has  to  be  squeezed  into  a 
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couple  of  kilobytes.  Another  planned  en¬ 
hancement  is  the  use  of  separate  read  and 
write  sector  buffers  for  each  physical 
drive,  so  when  programs  alternate  reading 
and  writing  they  won’t  force  the  same  big 
sectors  to  be  read  over  and  over.  Still 
another  is  the  mapping  of  four  logical 
drives  onto  two  physical  ones,  as  is  done 
in  the  IBM  PC.  Doing  this  and  maintain¬ 
ing  the  full  generality  of  use  for  all  four 
drives  turns  out  to  be  trickier  than  we 
thought,  but  it’s  possible  when  a  few  hun¬ 
dred  additional  bytes  don’t  matter. 

Fun  With  LINK80 

OK,  so  you  plan  a  much  larger  BIOS. 
Obviously  you  don’t  want  to  keep  it  as 
one  big  assembly;  it’s  too  difficult  to  edit 
and  too  tedious  to  assemble  that  way. 
You  want  the  BIOS  broken  into  lots  of 
small  modules,  each  with  a  well-defined 
set  of  functions  (we  ended  up  with  a 
dozen,  five  fixed  and  seven  banked).  It’s 
one  of  the  great  advantages  of  having  a 
linker  that  you  can  do  that  easily,  right? 

Wrong.  It  isn’t  easy  at  all  with  LINK- 
80,  because  a  two-part  BIOS  is  not  the 
sort  of  program  it  was  designed  to  link.  It 
doesn’t  help  that  the  manual  addresses 
the  use  of  the  program  only  as  an  adjunct 
to  PL/I-80  and  doesn’t  explain  it  as  a 
general  tool.  We  managed  it  in  the  end 
and  these  are  some  of  the  things  we 
learned  along  the  way. 

First,  the  “L”  option  determines  the 
origin  of  the  linked  program  and  the 
starting  point  of  the  linker’s  output  file.  If 
you  were  linking  a  (non-banked)  BIOS  that 
ran  at  F200h,  you  would  do  it  like  this: 

LINK80  BIOS  =  modules.  .  .  [LF200] 

That  produces  BIOS.COM,  containing 
just  the  code  of  the  given  modules,  linked 
to  an  origin  of  F200h.  The  same  effect 
can  be  had  with  the  “P”  option,  but  the 
resulting  file  contains  enough  binary 
zeroes  to  fill  storage  from  OlOOh  to  the 
program  origin  —  about  6 IK  of  them  in 
the  example.  We  can’t  figure  out  what  the 
“P”  option  is  good  for. 

Next,  the  “D”  option  determines  the 
origin  of  the  data  segments  of  the  linked 
modules,  while  the  “L”  option  sets  the 
origin  of  the  code  segments.  We  coded 
our  banked  BIOS  so  that  the  banked  mod¬ 
ules  consist  entirely  of  data  segments 
and  the  fixed  modules  are  entirely  code 
segments.  We  casually  assumed  that  a 
command  like 

LINK80  BJOS=modules.  .  . 

[D4000,LF200] 

would  link  the  banked  parts  to  an  origin 
of  4000h  and  the  fixed  parts  at  F200h. 
It  doesn’t.  It  produces  a  file  that  contains 
only  the  code  segments,  linked  to  F200h. 
The  data  segments  vanish.  In  fact,  LINK80 
will  never  write  any  output  that  would 
fall  below  the  “L”  load- point,  whatever 


segment  it  comes  from.  The  linking  is 
done  correctly  in  that  external  references 
have  correct  values,  but  the  data  they 
point  to  is  omitted  from  the  file  if  it  falls 
below  the  “L”  address. 

That’s  just  as  well,  because  we  weren’t 
thinking  too  clearly  when  we  devised  the 
command  above.  What  we  really  want  is 
two  separate  files,  FIX.COM  and  BNK. 
COM,  the  first  containing  the  code  that  is 
to  go  into  high,  global  storage  and  the 
second  containing  code  to  go  into  the 
banked  storage.  That  implies  that  LINK80 
has  to  process  each  group  of  modules  sep¬ 
arately.  But  each  section  has  references  to 
public  labels  in  the  other.  That  implies 
that  LINK80  has  to  process  all  modules 
together  in  one  run  so  that  it  can  resolve 
the  interlocking  references.  If  this  were  a 
movie,  our  computer  would  be  saying, 
“Contradiction,  does  not  compute”  in  a 
hollow  voice.  CP/M  3  is  supposed  to  have 
a  command  that  does  all  this,  but  we  are 
working  under  CP/M  2.2. 

Enter  the  Overlay 

Just  as  we  were  about  to  give  up,  we 
found  the  appendix  on  overlays  in  the 
LINK80  manual.  They  aren’t  explained 
very  well,  presumably  because  users  of 
PL/I-80  aren’t  supposed  to  be  concerned 
about  the  details.  But  in  fact,  LINK80’s 
overlay  feature  can  give  us  just  what  we 
need  for  the  present  problem. 

To  LINK80,  an  overlay  is  another 
program,  one  that  just  happens  •  to  be 
linked  at  the  same  time  as  some  main  pro¬ 
gram.  The  syntax  that  specifies  an  over¬ 
lay  is  identical  to  the  syntax  for  a  main 
program,  but  given  recursively  in  paren¬ 
theses.  The  command  lines  could  get  out 
of  hand,  except  that  they  can  be  continued 
by  appending  an  ampersand.  Here  is  how 
a  PL/ 1  user  might  link  a  program  with 


overlays : 

LINK80  ROOT=modules ...  & 

(0V1  =modules  .  .  . )  & 

(OV2=modules.  .  .  & 

(OV2A=modules .  .  . )  & 

(OV2B=modules .  .  .  )  ) 


That  command  would  create  five  output 
files:  ROOT.COM,  OVl.OVL,  0V2.0VL, 
OV2A.OVL,  and  OV2B.OVL.  Each  over¬ 
lay  file  is  a  separate  link,  composed  of  the 
modules  that  make  it  up  linked  to  an  ori¬ 
gin  that  is  the  end  of  its  root  module. 
OV1  and  0V2  will  be  linked  to  run  when 
loaded  at  the  byte  after  ROOT.COM; 
OV2A  and  OV2B  will  be  linked  to  run  at 
the  byte  following  OV2.  All  the  link  op¬ 
tions  apply,  independently,  within  the 
parenthetical  specification  of  an  overlay. 

The  code  in  an  overlay  may  refer  to 
public  labels  in  its  root  module,  but  not 
vice  versa.  That’s  all  right;  there  is  an  es¬ 
cape.  A  more  serious  problem  is  that 
LINK80  insists  on  adding  two  external 
references  to  a  root  program,  “?OVLAY” 
and  “?OVLAO.”  These  presumably  mean 


something  to  PL/I,  though  we  don’t  see 
why  the  compiler  couldn’t  generate  them 
in  the  usual  way.  They  have  to  be  sup¬ 
plied  because  there  won’t  be  any  output 
unless  all  external  references  are  resolved. 
We  resolve  them  by  writing  and  assem¬ 
bling  FAKE. ASM  as  follows: 

CSEG 

PUBLIC  ?OVLAY,?OVLAO 

70VLAY : 

70VLAO: 

END 

Now  we  can  create  FIX.OVL  and 
BNK.OVL,  the  two  sections  of  our  BIOS, 
with  all  external  references  resolved  and 
all  the  code  located  where  we  want  it. 
First,  FIX.OVL: 

LINK  FAKE  & 

(FIX  =  all-  12-bios-modules  & 
[D4000,LF200]  ) 

Because  it  loads  at  F200h,  none  of  the 
bank-BIOS  modules  will  be  included  in 
the  file  FIX.OVL.  However,  their  proper 
addresses  will  be  filled  in  where  needed. 
The  banked  section  is  trickier: 

LINK  FAKE, all-fixed-modules  & 
[LF200,$OZ]  & 
(BNK=all-banked -modules  & 
[L4000,$OA]  ) 

Here  we  let  LINK80  think  that  there  is  a 
root  module,  loading  at  F200h,  which 
contains  the  fixed  parts  of  the  BIOS.  The 
“$0Z”  switch  tells  it  not  to  produce  any 
output  for  this  “root”  module.  Then  we 
tell  it  to  make  BNK.OVL,  composed  of 
our  banked  modules  and  loading  at 
4000h,  the  base  of  our  banked  BIOS.  The 
“$0A”  switch  says  this  file  is  to  be  writ¬ 
ten.  All  the  places  in  the  banked  code 
that  refer  to  fixed  code  will  be  filled  in 
with  the  proper  addresses. 

And  that  is  how  one  treads  cautiously 
around  the  pitfalls  and  potholes  of  RMAC 
and  LINK80  to  get  a  two-section  BIOS 
written  and  linked.  The  result  is  two  files 
that  contain  the  code,  ready  to  be  loaded 
into  storage  in  their  correct  locations  and 
banks.  How  these  parts  are  put  together 
with  the  CCP  and  BDOS  of  CP/M  2.2 
and  written  onto  the  system  tracks  of  a 
diskette,  and  how  during  cold  start  they 
get  loaded  and  located  in  storage,  is  at 
least  two  other  stories.  But  arranging  the 
link  was  the  highest  hurdle  we  had  to  cross. 

Perhaps  that  wasn’t  the  most  fasci¬ 
nating  item  you’ve  read  in  this  column. 
Well,  you’ve  nobody  to  blame  but  your¬ 
self.  In  the  absence  of  questions  and  dis¬ 
coveries  from  readers,  our  only  source  of 
material  is  the  top  of  our  desk.  BBj 
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16-BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


CP/M  83  Show 

The  recent  CP/M  83  exhibition  in 
San  Francisco  drew  over  45,000  attendees, 
a  degree  of  success  surprising  even  to  its 
sponsors.  Browsing  through  the  booths,  I 
was  impressed  with  the  very  rapid  shift 
towards  16 -bit  microprocessors  that  has 
become  evident  over  the  last  year.  Almost 
every  new  machine  and  application  pro¬ 
gram  of  any  significance  was  based  on  an 
8086  or  68000,  though  Olivetti  was  also 
present,  valiantly  trying  to  rescue  the 
Z8000  from  oblivion.  There  was  almost 
nothing  worth  mentioning  in  the  way  of 
new  8 -bit  hardware  or  software,  with  one 
exception:  several  manufacturers  intro¬ 
duced  super- miniaturized  Z80  CP/M 
systems  in  which  the  whole  system  board 
and  a  slim -line  5”  disk  drive  fit  into  a 
chassis  smaller  than  a  shoebox. 

Digital  Research  itself  displayed 
many  new  products  at  the  show,  some  of 
which  indicate  marked  shifts  in  its  corpo¬ 
rate  goals.  CP/M-68K  was  shown  running 
on  five  different  machines  including  the 
Sage  and  Compu-Pro  68000-based  micro¬ 
computers.  It  comes  with  a  complete  set 
of  software  development  tools  including 
an  assembler  and  a  full-blown  C  compiler. 
Reportedly  CP/M-68K  will  eventually  be 
able  to  execute  as  a  task  under  UNIX, 


giving  its  users  the  best  of  both  worlds. 
The  same  C  compiler  will  be  available 
on  the  8086/88  in  April  1983.  Digital 
Research  also  announced  that  all  of  its 
future  operating  systems  products  and 
language  compilers  will  be  written  in  C! 
Evidently  DRI’s  previous  flagship  com¬ 
piler,  PL-1  subset  G,  is  being  relegated  to 
the  wings  forever. 

Also  announced  was  a  Digital  Re¬ 
search  version  of  “plain”  CP/M-86  for 
the  IBM  Personal  Computer,  including 
printer  spooling  and  the  new  graphics 
support  nucleus  GSX,  for  only  $60.00. 
DRI  has  been  discontented  with  IBM’s 
half-hearted  support  and  marketing  of 
CP/M-86,  and  is  now  showing  more  con¬ 
vincing  determination  to  capture  some  of 
the  enormous  (and  affluent)  PC  user  base 
from  Microsoft.  This  is  good  news  for  PC 
owners,  since  they  can  now  readily  afford 
both  PC-DOS  and  CP/M-86  and  there¬ 
fore  be  much  more  flexible  in  their  appli¬ 
cation  software  purchases.  But  such  a 
drastic  drop  in  price  will  surely  raise  ques¬ 
tions  in  the  minds  of  CP/M  owners  of 
other  machines,  who  must  still  pay  $150 
or  more  for  their  operating  systems. 

The  most  startling  development  of  all 
was  the  Digital  Research  display  of  an  ex¬ 
tended  LOGO  language  for  the  IBM  PC. 


A  seminar  on  the  new  product  was  given 
by  Gary  Kildall  himself,  who  described  it 
as  having  all  the  benefits  of  LISP  but  with 
a  “user-friendly”  programming  environ¬ 
ment.  Life  is  certainly  full  of  surprises. 

Intel  8087  News 

Hudson  Associates  has  announced  an 
8087  piggyback  board  for  the  Godbout 
8085/8088  Dual  CPU.  This  will  be  a  boon 
to  those  of  you  who  wish  to  take  advan¬ 
tage  of  the  8087  for  fast  floating-point 
math  but  don’t  want  to  trash  your  present 
CPU  board  for  a  new  $750  Godbout 
8086/87  board.  The  procedure  for  instal¬ 
ling  the  piggyback  board  is  very  simple: 
remove  the  8088  from  your  present  CPU 
board,  plug  the  piggyback  board  into  the 
8088’s  socket,  then  plug  the  8088  and 
8087  chips  into  the  piggyback  board.  The 
system  should  then  boot  up  and  run  just 
as  before. 

This  piggyback  board  will  probably 
also  work  on  other  8088  CPU  boards 
such  as  the  Lomas  LPD-88.  The  main 
consideration  is  whether  adequate  power 
is  delivered  to  the  8088’s  socket  to  supply 
both  processors.  The  8087  draws  consi¬ 
derably  more  power  (up  to  475  mA)  than 
the  8088  (340  mA).  We  have  used  a  simi¬ 
lar  hand-wired  piggyback  board  to  add  an 


Description 

Command 

AR68 

Archive  utility,  stores  object  files  in  the  C 
run-time  library 

AS68 

C 

68000  assembler 

C  language  compiler 

Offset 

Contents 

CP68 

C  language  preprocessor  for  macros 

0000-0003 

Lowest  address  of  Transient  Program  Area 

DDT 

Interactive  68000  debugger 

0004-0007 

1  +  highest  address  of  TPA 

DIR 

Display  disk  file  directory 

0008 -000B 

Starting  address  of  the  Text  Segment 

DIRS 

Display  directory  of  “system”  files 

000C-000F 

Length  of  Text  Segment  (bytes) 

DUMP 

Display  contents  of  a  file  in  hex  and  ASCII 

0010-0013 

Starting  address  of  the  Data  Segment 

ED 

Line  editor 

0014-0017 

Length  of  Data  Segment 

ERA 

Erase  file(s) 

0018-001 B 

Starting  address  of  the  bss  (uninitialized  data) 

L068 

Linker 

00 1C -00  IF 

Length  of  bss 

NM68 

Symbol  table  display  utility 

0020-0023 

Length  of  free  memory  after  bss 

PIP 

Transfer,  concatenate,  and/or  filter  files 

0024-0024 

Drive  from  which  the  program  was  loaded 

between  various  peripheral  devices 

0025-0037 

Reserved 

RELOC 

Relocate  a  command  file  to  an  absolute  address 

0038  -005B 

2nd  parsed  FCB  from  command  line 

SENDC68 

Convert  command  file  to  Motorola  S-record 

005C-007F 

1st  parsed  FCB  from  command  line 

format 

0080-00FF 

Command  tail  and  default  DMA  buffer 

SIZE68 

Print  the  size  of  a  command  file 

Table  1 . 

Table  2. 

CP/M-68K  Commands  and  Utilities 

Program  Base  Page  Format  for  CP/M-68K 
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8087  to  the  NEC  8086-based  Advanced 
Personal  Computer  without  any  problems. 
Hudson  Associates  may  be  contacted  at 
P.O.  Box  2957,  Santa  Clara,  CA  95055. 

A  LlNK-80-compatible  run-time  li¬ 
brary  for  8087  support  has  been  released 
by  Avant-Code,  1508-A  Oxford  Street, 
Berkeley,  CA  94709.  The  library  costs 
$200  and  may  be  used  with  Fortran-80, 
Bascom-80,  Cobol-80,  or  Macro-80.  Of 
course,  you  need  to  run  the  linked  pro¬ 
grams  on  a  system  containing  the  Godbout 
Dual  CPU,  since  the  8088  must  take  over 
control  in  order  to  perform  the  math 
operations  on  the  8087. 


Preview  of  CP/M-68K 

The  information  presented  here  is 
abstracted  from  the  new  CP/M-68K 
documentation  set  which  was  recently 
released.  CP/M-68K  is  logically  symmet¬ 
rical  to  the  CP/M-80  and  CP/M-86  oper¬ 
ating  systems,  with  enhancements  to  sup¬ 
port  the  16 -megabyte  memory  addressing 
space  of  the  68000  microprocessor.  The 
disk  file  structure  is  exactly  compatible 
with  the  8080  and  8086/88  versions,  and 
supports  a  maximum  of  16  drives  with  up 
to  5  1 2  megabytes  per  drive. 

The  operating  system  resides  in  a  file 
named  “CPM.SYS”  and  is  loaded  into 
memory  by  a  cold-start  routine  which  is 
initially  read  in  from  the  two  reserved 
system  tracks  (similar  to  CP/M-86).  All 
of  the  modules  (CCP,  BDOS,  and  BIOS) 
of  CP/M-68K  remain  resident  at  all  times. 
The  CCP  and  BDOS  are  written  in  C,  and 
the  BIOS  of  course  is  written  in  assembly 
language  by  the  system  implementor. 

CP/M-68K  contains  most  of  the  fa¬ 
miliar  CP/M  commands,  as  well  as  some 
impressive  new  program  development 
tools  (see  Table  1).  The  inclusion  of  a 
version  7,  C-compatible  compiler  is  a  tre¬ 
mendous  enhancement.  Preliminary 
benchmark  results  indicate  that  this  com¬ 
piler  generates  very  efficient  code  (see 
Jim  Gilbreath’s  article  in  the  January 
1983  BYTE). 

Transient  application  programs  are 
designated  in  the  disk  directory  with  the 
extension  “68K.”  A  program  may  be 
loaded  via  a  command  line  at  the  CCP 
level  or  by  another  program  through 
BDOS  funtion  59.  After  a  program  is 
loaded,  the  Transient  Program  Area 
(TPA)  contains  the  base  page,  the  pro¬ 
gram  segments  (text,  data,  and  bss).  and 
the  user  stack  (see  Table  2  and  Figure  1). 

The  CP/M-68K  BDOS  functions  are 
very  similar  to  CP/M-86,  except  that  the 
memory  management  functions  are  not 
included.  A  typical  calling  sequence  is  as 
follows: 

move.w  #2,D0.W  ;move  function  number 
;to  the  first  data  register 


move.w  #7,D1.W  ;move  ASCII  bell  code 
;to  the  second  data 
:  register 

trap  #2  jrequest  BDOS  function 

;to  output  a  character 


Any  results  are  returned  in  D0.W.  A 
few  of  the  BDOS  functions  are  different 
or  new  compared  to  the  previous  operat¬ 
ing  systems  and  will  be  described  briefly 
below. 

Function  12  (return  version  number) 
yields  the  value  2022H  in  register  D0.W, 
signifying  a  68000-CPU,  single-user  envi¬ 
ronment  without  networking,  and  BDOS 
version  2.2. 

Function  50  is  a  direct  BIOS  call 
which  allows  application  software  to  ma¬ 
nipulate  the  primitive  device  drivers.  The 
Dl.L  register  contains  the  address  of  the 
BIOS  Parameter  Block,  a  five-word  mem¬ 
ory  area  containing  the  desired  function 
number  and  two  other  32-bit  paramenters. 
Any  results  are  again  returned  in  register 
D0.W. 

Funtion  59  loads  an  executable  pro¬ 
gram  file  into  memory.  The  address  of  a 
Load  Parameter  Block  (LPB)  is  passed  in 
register  Dl.L.  The  LPB  describes  the  pro¬ 
gram  and  specifies  the  load  address;  it 
includes  the  following  items: 


•  address  of  File  Control  Block  of 
successfully  opened  program  file 

•  lowest  address  of  area  in  which  to 
load  program 

•  highest  address+  1  of  area  in  which  to 
load  program 

•  address  of  base  page  (returned  by 
BDOS) 

•  default  user  stack  pointer  (returned 
by  BDOS) 

•  loader  control  flags 

The  BDOS  allocates  memory  for  the 
desired  program  and  base  page  and  initia¬ 
lizes  locations  0000-0024H  of  the  latter. 
Locations  0025-0037H  are  not  initialized. 
The  calling  program  must  fix  up  any  addi¬ 
tional  program,  first  pushing  a  return  ad¬ 
dress  on  the  stack  if  it  wishes  to  resume 
execution  later. 

Funtion  61  (Set  Execution)  allows  a 
program  to  link  its  own  handlers  to  the 
operating  system  for  such  events  as  bus 
errors,  illegal  instructions,  and  zero  divide. 

Function  62  sets  the  calling  program 
into  Supervisor  State  and  swaps  to  the 
system  stack.  Presently  this  call  is  always 
successful,  though  in  future  versions  (es¬ 
pecially  multi-user  systems)  the  function 
may  not  be  present  or  may  require  cer¬ 
tain  privilege  attributes. 


High  Memory 


Low  Memory 


CP/M-68K  Operating  System 


User  Stack 


Free  Memory 


Uninitialized  Data 


Initialized  Data 


Text  Segment 


Base  Page 


Exception  Vectors 
(reserved  for  use  by  system) 


Figure  1. 

CP/M-68K  Memory  Map 
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In  forthcoming  columns  we  will  pro¬ 
vide  examples  and  benchmarks  of  pro¬ 
grams  run  under  CP/M-68K,  and  begin  to 
publish  some  68000  utility  subroutine 
listings. 


Improved  Square  Root  Routines 

Don  Taylor  of  Corvallis,  Oregon 
writes:  “If  you  are  going  to  do  square 
roots,  and  you  have  assembly  language 
access,  don’t  use  Newton’s  Method.  It  is 
a  fine  tool,  and  very  general  purpose,  but 
too  slow  for  something  as  simple  as  this. 
1  don’t  remember  where  I  first  ran  across 
the  integer  bit-by-bit  method,  but  typi¬ 
cally  it  is  an  order  of  magnitude  faster. 

“The  idea  behind  the  enclosed  square 
root  routine  is  very  similar  to  the  way 
that  it  is  done  by  hand,  except  for  the 
fact  that  the  process  is  even  simpler  in 
base  2.  In  decimal  you  use  pairs  of  digits, 
in  binary  you  use  pairs  of  bits.  In  decimal 
you  must  guess  the  next  trial  digit,  in  bi¬ 
nary  it  can  only  be  zero  or  one. 

“If  you  breakpoint  the  routine  at  the 
bottom  of  the  loop,  you  can  see  the  par¬ 
tial  result  growing  bit-by-bit.  In  addition, 
the  remainder  should  not  exceed  the  trial 
root.  If  the  remainder  exceeds  half  the 
root  at  the  end  of  the  routine,  the  root 
can  be  better  approximated  by  increasing 
it  by  one;  without  doing  this  the  root  will 
always  be  less  than  or  equal  to  the  real 
square  root.” 

Our  thanks  to  Don  for  this  interest¬ 
ing  and  elegant  subroutine.  A  listing  in 
Intel  8086  mnemonics  accompanies  this 
column  on  page  82. 


»»J 
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Integer  Square  Root 

(Text  begins  on  page  79) 


title  ’Integer  Square  Root’ 
pagewidth  79 

Integer  Square  Root  tor  8086/88 
Contributed  by  Don  Taylor 

Cal  1  with:  AX  =  Argument 

Returns:  AX  =  Square  root 

Other  registers  preserved 


oooo 

53 

sqrt : 

push 

bx 

; save  registers 

000 1 

51 

push 

cx 

0002 

52 

push 

dx 

0003 

8BDO 

mov 

dx ,  ax 

; argument  into  DX 

0005 

B 9 0800 

mov 

cx ,  8 

; number  ot  iterations 

0008 

33DB 

xor 

bx ,  bx 

; cl ear  the  remainder 

OOOA 

8BC3 

mov 

ax ,  bx 

jclear  trial  value  and 
; final  result  store 

OOOC 

D1E3 

sqrt 1 : 

shl 

bx ,  1 

;double  partial  result 

000E 

43 

i  nc 

bx 

; guess  next  bit  is  a  1 

OOOF 

D1E2 

shl 

dx,  1 

; fetch  2  new  bits 

001 1 

DIDO 

rcl 

ax ,  1 

;from  argument 

0013 

D1E2 

shl 

dx ,  1 

0015 

DIDO 

rcl 

ax ,  1 

0017 

2BC3 

sub 

ax ,  bx 

;do  a  trial  subtraction 

0019 

7308 

0023 

jnc 

sqrt2 

} guess  was  right, 

; append  a  1  bit 

OOIB 

03C3 

add 

ax ,  bx 

; guess  wrong,  put  it 
;  back 

OOID 

4B 

dec 

bx 

; and  clean  up  for 
;next  pass 

00  IE 

E2EC 

OOOC 

1  oop 

sqrt  1 

0020 

E90300 

0026 

jmp 

sqrt3 

;go  scale  result 

0023 

43 

sqrt2: 

i  nc 

bx 

;convert  xxxxOl  to 
;xxxxlO,  i.e.  append 
; a  1  bit 

0024 

E2E6 

OOOC 

1  oop 

sqrt  1 

0026 

D1FB 

sqrt3: 

sar 

bx ,  1 

;divide  by  2  to  get 
; actual  square  root 

0028 

8BC3 

mov 

ax ,  bx 

; return  result  in  AX 

002A 

5A 

pop 

dx 

; restore  other  registers 

002B 

59 

pop 

cx 

002C 

5B 

pop 

bx 

002D 

C3 

ret 

END  OF  ASSEMBLY-  NUMBER  OF  ERRORS:  O.  USE  FACTOR:  07. 

A> 


End  Listing 
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SOFTWARE  REVIEW 

Unica  and  XM-80 


by  Michael  Favitta 


Product:  Unica  and  XM-80 
From:  Knowlogy 

P.O.Box  283  -  E 
Wilsonville,  OR  97070 
$195.00  ($95.00  Unica  only) 

Reviewed  by  Michael  Favitta 

Knowlogy  advertises  that  its  software 
package  “brings  a  Unix-like  environment” 
to  any  Z80-based  computer  system  run¬ 
ning  CP/M  version  2  or  beyond.  The  Unix 
environment  is  simulated  by  using  a  set  of 
utility  programs  that  possess  Unix-like 
attributes.  If  you  purchase  XM-80,  you 
will  also  need  Microsoft’s  MACRO-80 
assembler  and  LINK-80  loader. 

The  package  is  divided  into  two  inde¬ 
pendent  parts,  the  executable  modules 
called  Unica  and  the  language  translator 
XM-80.  The  Unica  are  a  group  of  file- 
related  utility  programs  that  perform 
functions  such  as  delete,  copy  and  search. 
They  are  written  in  the  XM-80  language 
and  the  source  for  each  is  provided.  The 
XM-80  translator  converts  the  XM-80 
source  modules  into  standard  Z80  assem¬ 
bly  language.  The  Unica  may  be  purchased 
without  XM-80  for  $95.  If  desired,  XM- 
80  may  then  be  added  at  a  later  date  for 
the  cost  difference  plus  a  $10  handling 
charge.  You  may  also  purchase  new  and 
enhanced  Unica  as  they  become  available 
but  Knowlogy  does  not  indicate  what  the 
fee  for  this  service  will  be. 

Unica 

The  Unica  part  of  the  package  con¬ 
sists  of  eighteen  COM  files,  each  of  which 
performs  one  function  and  is  referred  to 
as  a  command.  To  create  the  Unix-like 
environment,  all  commands  support  re¬ 
direction  of  standard  I/O  to  any  device 
or  disk  file,  multiple  commands  linked 
together  via  “pipes,”  and  filename  conven¬ 
tions  that  support  user  numbers  and 
extended  wild  card  capabilities. 

The  commands  provided  are: 

BC  Binary  file  comparator  that 

displays  differences  between 
two  files. 

CAT  Concatenates  one  or  more  files. 

CP  Copies  one  or  more  files. 

DM  Prints  a  disk  allocation  map. 

FID  Computes  a  1 6-bit  checksum 
for  a  file. 

HC  Concatenates  one  or  more  files 
horizontally  (by  line). 

LN  Creates  an  alias  for  a  file  via  a 
directory  link. 


LS  Lists  the  directory  contents. 

MV  Renames  (moves)  one  or  more 

files. 

RM  Deletes  (removes)  one  or  more 

files. 

SC  Source  file  comparator  that 

displays  differences  between 
two  files. 

SFA  Sets  and  changes  file  attributes. 

SP  Spelling  error  detector. 

SR  Pattern  searching  with  wild  cards. 
SRT  Sorts  lines  of  a  file  by  text  in 
specified  columns. 

TEE  A  “pipe  fitting”  used  to  direct 
output  to  more  than  one 
command. 

WC  Counts  the  characters,  words,  and 
lines  in  one  or  more  files. 

WX  Extracts  words  from  one  or  more 
files. 

Each  command  has  a  set  of  flags 
associated  with  it  that  are  used  to  specify 
procession  options.  Flags  consist  of  a 
minus  sign  followed  by  one  or  more  let¬ 
ters.  They  may  appear  separately  or  in 
groups,  any  place  in  the  command  line. 
Two  of  the  most  useful  flags  are  the  N 
and  V  flags.  The  N  flag  prints  the  name  of 
each  file  as  it  is  processed.  The  V  flag 
takes  this  a  step  further  and  allows  you  to 
verify  that  processing  should  be  carried 
out  on  each  file  specified.  This  allows 
wild  card  filenames  to  be  used  freely,  as 
you  can  prevent  any  file  from  being  pro¬ 
cessed  even  though  it  matches  the  wild 
card.  This  feature  can  prevent  some  costly 
mistakes  when  using  a  command  such  as 
RM  to  delete  files. 

Many  of  the  commands  are  more 
useful  than  the  brief  descriptions  of  them 
above  may  indicate.  The  commands  CP, 
HC,  and  SRT  are  such  commands  and 
merit  further  discussion.  The  spelling 
error  detector  (SP)  also  needs  some  ex¬ 
planation  as  it  was  the  only  Unicum  that 
performed  poorly. 

The  copy  command  (CP)  has  all  the 
capabilities  of  PIP  except  for  the  data 
conversion  functions  (such  as  converting 
the  output  to  upper  case).  In  addition,  CP 
allows  you  to  set  or  change  file  attributes 
and  will  not  overlay  a  file  that  is  marked 
as  write-locked.  It  can  copy  a  file  to  the 
same  disk  so  you  can  make  backup  copies 
easily  on  a  single-disk  system.  The  com¬ 
mand  is  designed  for  maximum  disk 
efficiency  as  it  uses  all  available  memory 
for  buffers  and  always  reads  as  much  as 
possible  before  writing.  In  my  tests,  I 


found  that  CP  was  about  twenty  percent 
faster  than  PIP  when  two  or  more  files 
were  being  copied.  When  copying  one  file 
they  were  about  the  same  speed.  As  with 
all  file-related  commands,  extended  wild 
card  capabilities  are  present  that  can  be 
controlled  with  the  V  flag. 

The  horizontal  concatenate  command 
(HC)  does  a  lot  more  than  just  append 
lines  together.  If  you  specify  different  sets 
of  flags,  HC  will  expand  tabs  to  spaces, 
compress  spaces  to  tabs,  add  leading 
spaces,  remove  trailing  spaces,  print  one 
or  more  files  side  by  side  starting  at  any 
column  position,  and  append  a  string 
constant  to  each  line  of  a  file.  It  is  a 
handy  tool  for  reformatting  text  to  fit 
various  terminal  screen  widths  and  for 
converting  files  from  other  systems  to 
your  own  space/tab  conventions. 

The  data  sorting  utility  (SRT)  sorts 
the  contents  of  a  file  into  alphabetical  or¬ 
der.  The  size  of  the  file  that  can  be  sorted 
is  determined  by  your  system’s  memory 
size,  as  sort  is  done  in  memory  using  the 
Quicksort  algorithm.  A  primary  sort  key 
field  can  be  specified  by  using  flags  to  set 
the  column  positions.  In  this  case  the  rest 
of  the  line  will  be  used  as  a  secondary 
sort  key. 

The  spelling  error  detector  (SP)  cre¬ 
ates  a  list  of  all  the  words  in  a  file  that  it 
does  not  find  a  match  for  in  its  dictionary 
of  23,688  words.  Unfortunately,  the  dic¬ 
tionary  does  not  include  plurals  or  conju¬ 
gated  verbs  and  there  is  no  facility  to  add 
new  words.  These  limitations  are  docu¬ 
mented  and  Knowlogy  promises  to  up¬ 
grade  this  command— in  the  future.  In 
actual  testing,  a  document  that  contained 
773  words  had  680  of  them  flagged  as 
possible  errors.  Only  74  of  the  words 
flagged  were  actually  incorrect  (e.g.,  mis¬ 
spelled,  acronyms).  Not  wanting  to 
believe  the  results,  I  created  a  file  that 
contained  35  common  words  and  ran  SP 
again.  To  my  disappointment,  it  flagged 
28  of  the  words  as  possible  spelling  errors. 
This  was  also  the  only  Unicum  that  I 
found  any  software  problems  with.  SP 
causes  a  system  crash  if  the  dictionary 
file  is  not  present  when  it  is  executed.  In 
its  current  form,  the  SP  Unicum  is  not 
worth  using. 

The  Unica  package  is  more  than  just 
a  set  of  independent  utility  programs. 
The  commands  may  be  linked  together  to 
form  complex  procedures.  These  connec¬ 
tions  are  called  pipes.  Along  with  the  abil¬ 
ity  to  redirect  the  output  of  a  command 
to  any  device  or  file,  pipes  create  a  flex- 
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ibility  that  makes  the  Unica  package  a 
worthwhile  investment.  The  following 
examples  demonstrate  the  command  line 
syntax,  the  redirection  of  output,  and  the 
use  of  pipes. 

CAT  filel  file 2  I 

SR  “find  this” -1  >b:  file3.ext;2 

This  command  string  concatenates 
filel  and  file2  in  a  temporary  file  that  is 
passed  to  SR.  SR  writes  the  line  number 
and  line  to  file3.ext  on  drive  b  for  each 
line  that  contains  the  string  “find  this.” 
File3.ext  is  associated  with  user  number  2. 

WX  -v  *.doc  I  TEE  con:  I  SRT  -u  I 

TEE  1st:  >  filel 

This  command  string  extracts  a  list 
of  all  words  used  in  all  files  that  have  a 
.doc  extension  on  the  currently  logged 
drive.  You  will  be  prompted  to  verify 
that  you  really  want  to  process  each  file. 
The  extracted  words  are  printed  on  the 
console  and  piped  to  the  sort  (SRT)  com¬ 
mand  to  sort  the  list  of  words  and  remove 
all  duplicates.  The  sorted  list  is  written  to 
the  printer  and  filel . 

With  the  exception  of  SP,  I  found 
the  Unica  package  to  be  well  though  out 
with  respect  to  what  commands  were  pro¬ 
vided  and  how  they  interacted  when  con¬ 
nected  via  pipes.  Each  command  worked 
exactly  as  documented.  Not  all  the  com¬ 
mands  worked  perfectly  in  every  case  but 
the  cases  that  caused  problems  were  clearly 
defined  in  a  “bugs”  section  for  each  com¬ 
mand.  Besides  SP  causing  a  system  crash 
when  the  dictionary  was  not  present,  the 
only  problem  1  encountered  had  to  do 
with  the  physical  size  of  the  package.  I 
have  single-density  8-inch  disk  drives  that 
have  a  formatted  capacity  to  250  Kbytes. 
The  Unica  without  the  spelling  diction¬ 
ary  (another  73  Kbytes)  take  up  222 
Kbytes  of  storage.  This  leaves  very  little 
room  on  a  single  disk  for  other  utilities 
and  text  or  source  files.  Since  all  tempor¬ 
ary  files  that  are  created  during  proces¬ 
sing  (via  pipes)  reside  on  the  currently 
logged  disk,  the  problem  is  compounded. 
This  problem  can  be  overcome  by  using 
more  than  one  drive.  You  then  must  spe¬ 
cify  the  drive  for  all  the  files  and  com¬ 
mands  that  do  not  reside  on  the  currently 
logged  drive.  This  procedure  can  be  quite 
frustrating  as  there  is  a  much  greater 
chance  for  human  error,  especially  when 
entering  complicated  command  sequen¬ 
ces.  Dual-density  disk  drives  significantly 
enhance  the  practical  usability  of  this 
product. 

XM-80 

XM-80  is  a  programming  language 
that  stresses  the  design  of  programs  into 
modules  that  can  be  used  in  more  than 
one  program.  The  analogy  of  an  electrical 
engineer,  selecting  existing  integrated  cir¬ 
cuits  and  wiring  them  together  to  per¬ 
form  a  required  function  versus  using  all 


84 


discrete  components,  is  used  to  describe 
this  approach.  Knowlogy  calls  this  meth¬ 
odology  “software  synthesis.”  In  keeping 
with  the  analogy,  each  module  is  called  a 
component  and  related  components  are 
grouped  into  families.  Two  families  of 
components  are  supplied  with  XM-80. 
The  2800  family  consists  of  components 
for  the  Z80  that  are  not  hardware  or  soft¬ 
ware  dependent.  The  2801  family  are 
components  that  require  CP/M  version  2 
or  beyond.  All  the  Unica  are  built  from 
the  components  in  these  two  families, 
“wired”  together  with  Z80  assembly  lan¬ 
guage.  The  source  code  for  the  two 
component  families  is  not  provided. 
Knowlogy’s  software  licensing  agree¬ 
ment  does  allow  you  to  freely  distrib¬ 
ute  any  software  that  you  develop, 
even  if  it  contains  one  or  more  of  the 
components.  The  agreement  limits  the 
distribution  of  any  programs  derived 
from  a  Unicum  to  other  license  holders. 

XM-80  is  an  acronym  for  an  exten¬ 
sion  of  Microsoft’s  8080/Z80  assembler, 
MACRO-80.  The  XM-80  compiler  trans¬ 
lates  XM-80  procedures  and/or  procedure 
calls  into  standard  Z80  assembly  language 
that  can  be  assembled  by  MACRO-80. 
Any  line  that  is  not  recognized  as  an  XM-80 
statement  is  passed  through  unchanged, 
allowing  any  mixture  of  assembly  lan¬ 
guage  and  XM-80  to  be  used  in  writing 
XM-80  programs.  Using  XM-80  forces 
programmers  to  abide  by  a  rigidly  de¬ 
fined  set  of  interface  rules  when  writing 
new  components.  These  include  compo¬ 
nent  naming  and  documentation  conven¬ 
tions.  By  forcing  adherence  to  the  compo¬ 
nent  interface  rules  for  each  component, 
the  XM-80  compiler  can  validate  that  the 
arguments  passed  and  the  registers  used 
by  the  specified  procedure  are  correct. 
The  end  result  of  using  a  tool  such  as 
XM-80  is  to  increase  programmer  produc¬ 
tivity  and  decrease  program  development 
time  by  not  reinventing  the  wheel  for 
each  new  application.  The  compiler  also 
reduces  the  possibility  of  program  errors 
caused  by  passing  parameters  to  subrou¬ 
tines  incorrectly. 

The  following  is  a  summary  of  XM-80 
programming  guidelines  and  syntax. 

The  rules  for  XM-80  program  devel¬ 
opment  are: 

(1)  Search  through  the  available 
components  and  select  those  which  are 
applicable  to  the  project. 

(2)  Define  any  new  components 
needed.  Code,  test,  and  document  each 
new  component.  Enter  the  completed 
component  and  documentation  into  the 
correct  family  library. 

(3)  “Wire”  together  the  components 
with  assembly  language  to  produce  the 
completed  program. 

The  interface  rules  for  components 

are: 


(1)  Component  names  consist  of  up 
to  six  upper- case  letters  to  identify  the 
component,  followed  by  a  four-digit 
family  name,  followd  by  two  lower-case 
letters  to  denote  the  author.  If  more  than 
one  global  symbol  exists  fora  component, 
then  three  letters  are  used  to  identify  the 
component  and  global  symbols  are  created 
by  appending  up  to  three  letters  to  the 
component  name. 

(2)  The  syntax  for  procedure  defini¬ 
tion  and  procedure  calling  is  demonstrated 
by  the  examples  below. 

proc  GETNUM  [CHAN:  stk]  -> 
[ERROR:a,NUM:  hi]  +C-de 

begin 

Source  code  (can  include  calls  to 
other  components) 

end  GETNUM 

The  procedure  GETNUM  is  defined  as 
having  one  input  parameter  that  is  passed 
on  the  stack.  An  error  code  is  returned 
in  the  accumulator  and  a  number  in  the 
HL  register  pair.  The  carry  flag  is  altered 
and  register  pair  DE  is  destroyed. 

The  GETNUM  procedure  is  called  by: 

GETNUM  [stk=(VALUE)]  -*• 
[a,SAVEHL=hl]  +C-de 
The  contents  of  the  16-bit  word  pointed 
to  by  VALUE  are  pushed  onto  the  stack 
and  then  the  procedure  GETNUM  is 
called.  The  contents  of  register  pair  HL 
are  stored  at  SAVEHL  after  the  return. 

The  procedure  definition  is  also  en¬ 
tered  in  a  special  file  called  the  component 
interface  file  (CIF).  The  CIF  is  used  for 
parameter  error  checking  by  the  XM-80 
compiler.  Note  that  the  registers  destroyed 
by  the  called  routine  must  be  listed  on 
the  procedure  call.  These  are  checked  by 
the  compiler  to  make  sure  that  the  pro¬ 
grammer  is  aware  of  all  registers  that  will 
be  affected  by  the  procedure  call. 

The  XM-80  compiler  understands 
several  statements  besides  those  used  in 
procedure  calling  and  definition.  These 
statements  are  used  to  give  the  program¬ 
mer  control  over  how  XM-80  sets  up  pro¬ 
cedure  linkages  and  where  needed  CIF 
files  can  be  found.  The  compiler  can  also 
be  instructed  to  generate  inline  code  if  de¬ 
sired.  The  compiler  itself  is  not  a  Unicum 
so  it  does  not  support  any  of  the  Unica 
capabilities  such  as  redirection  of  output. 
It  uses  a  command  syntax  similar  to  that 
of  MACRO-80.  Most  of  the  command 
line  is  used  to  generate  a  MACRO-80  call 
after  XM-80  is  done.  The  XM-80  compil¬ 
er  is  controlled  by  specifying  a  set  of 
flags  similar  to  those  used  with  the  Unica 
at  the  end  of  the  command  line. 

Again,  the  package  worked  as  docu¬ 
mented  although  the  “known  bugs”  sec¬ 
tion  documented  some  serious  problems 
(note  that  the  version  I  reviewed  was  re¬ 
leased  in  March  1981).  The  worst  of  these 
is  that  if  you  enter  the  extension  on  the 
source  input  file,  it  is  deleted.  I  would 
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have  liked  to  have  seen  a  warning  at  the 
very  front  of  the  manual  about  this  prob¬ 
lem,  as  it  is  an  easy  mistake  to  make  and 
the  consequence  could  be  hours  of  lost 
work.  The  XM-80  package  is  a  worthwhile 
assembly  language  programming  develop¬ 
ment  tool.  It  includes  an  extensive  set  of 
library  components  that  could  save  many 
times  the  price  of  the  package  in  pro¬ 
grammer  time.  An  added  bonus  is  that  by 
using  the  I/O  components  provided,  your 
programs  can  contain  all  the  features  that 
the  Unica  possess,  including  the  ability  to 
build  pipes. 

Unica  and  XM-80  Documentation 

The  documentation  for  Unica  and 
XM-80  comes  in  a  three-ring  notebook 
with  labeled  dividers  that  make  it  simple 
to  find  a  desired  section.  This  format 
makes  it  easy  to  add  to  and  update  the 
manual  as  you  develop  new  Unica  or  XM- 
80  components.  My  one  big  gripe  with 
the  manual  is  that  it  doesn’t  have  a  usable 
page-numbering  scheme.  All  Unica  and 
components  start  at  page  1 .  This  makes 
an  index  useless,  so  Knowlogy  did  not  in¬ 
clude  one.  There  isn’t  a  table  of  contents 
or  any  kind  of  summary  of  which  Unica 
and  components  come  with  the  package 
either.  This  means  you  have  to  read  the 
entire  manual  to  get  a  feel  for  what  the 
package  offers.  The  manual  becomes  tedi¬ 
ous  to  use  once  you’ve  become  familiar 
with  the  package  and  just  want  to  use  the 
manual  as  a  reference.  This  problem  could 
be  solved  easily  by  the  addition  of  a 
couple  of  appendices  with  summaries  of 
the  Unica  and  XM-80  components  and 
their  associated  syntax  and  argument  lists. 

Putting  format  aside,  the  manual  is 
written  carefully  and  thoroughly  de¬ 
scribes  the  product  and  how  to  use  it. 
Examples  are  used  liberally  throughout 
the  text  to  demonstrate  what  the  various 
Unica  do  and  how  they  can  be  combined 
to  perform  other  functions.  For  XM-80, 
an  example  is  provided  that  takes  you 
from  program  design,  through  testing,  to 
program  completion.  Detailed  data  sheets 
are  provided  for  each  of  the  components. 
The  source  codes  for  the  Unica  can  also 
be  used  as  an  excellent  tutorial  on  how  to 
write  XM-80  programs,  as  they  are  well 
written  and  extensively  commented. 

Knowlogy  dispenses  a  good  deal  of 
software  design  philosophy  along  with 
the  hows  and  whys  of  Unica  and  XM-80. 
This  makes  the  manual  read  more  like  a 
textbook  than  a  reference  manual.  (This 
probably  has  something  to  do  with  why 
they  chose  “Knowlogy”  as  a  company 
name.)  The  entire  package  is  presented  as 
a  complete  methodology  on  how  to  solve 
problems  with  a  computer,  with  the 
Unica  part  of  the  package  an  end  result  of 
the  methodology.  Personally,  I  like  this 
approach  and  think  the  resulting  manual 
is  one  of  the  best  that  I  have  seen  with 
respect  to  content. 


Summary 

The  Unica  are  a  group  of  utility  pro¬ 
grams  that  use  an  extended  CP/M  com¬ 
mand  sequence  that  allows  the  output  of 
one  command  to  be  used  as  the  input  to 
another.  With  the  exception  of  the  spelling 
command  (SP),  all  the  Unica  worked  as 
documented  and  would  make  a  useful  ad¬ 
dition  to  just  about  anyone’s  set  of  utility 
programs.  Even  without  SP,  I  think  the 
Unica  package  is  well  worth  $95. 

XM-80  is  a  software  development 
tool  designed  to  increase  programmer 
productivity.  If  the  “software  synthesis” 
methodology  is  followed,  then  this  tool  is 
a  worthwhile  investment.  If  you  can’t  live 
within  the  rigid  framework  defined  by 
the  methodology,  then  I  would  suggest 
saving  the  extra  $100  that  XM-80  costs. 
To  get  the  most  out  of  the  entire  package, 
you  should  design  your  programs  with 
the  existing  components  that  provide  the 
special  features  used  by  the  Unica. 

Overall,  the  Unica/XM-80  software 
product  is  designed  and  documented  very 
well.  The  package  I  received  did  have  a 
few  problems,  which  I  presume  will  be 
corrected  in  later  releases,  but  most  are 
documented  and  can  be  programmed 
around. 

We  checked  with  Knowlogy  to  see  if 
there  had  been  upgrades  from  the  release 
that  our  reviewer  received.  We  were  in¬ 
formed  that  they  have  indeed  released  an 
upgraded  version  that  has  several  improve¬ 
ments,  among  them  a  redone  spelling 
error  detector  which  now  has  a  dictionary 
of  130,000  words  (including  plurals  and 
conjugations)  and  the  ability  to  add  new 
words.  —  Ed. 
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OF  INTEREST 


Baudy  Modem 

Modems  with  1200  baud  are  lower¬ 
ing  in  price.  Racal-Vadic’s  VA212LC 
costs  $550.  The  Bell-compatible, 
switched -network,  originate/answer 
full-duplex  modem  operates  at  1200, 
or  0  to  300  for  communications  with 
slower  systems,  automatically  deter¬ 
mining  the  baud  rate  of  a  calling 
modem.  Auto-answer  can  be  disabled 
to  obviate  answering  calls  on  lines  that 
carry  both  voice  and  data.  Five  LEDs 
display  operational  status,  monitoring 
transmit  and  receive  data,  carrier 
detect,  voice/data  status,  and  bit  rate; 
and  the  unit  continually  monitors  itself 
with  automatic  self-test  routines.  The 
VA212LC  automatically  handles  9-  or 
10-bit  character  codes,  and  thus  trans¬ 
mits  EBCDIC  or  ASCII.  Reader  Ser¬ 
vice  No.  101. 


A  Genius  for  Displays 

Many  of  the  newer  dedicated 
word  processing  systems  and  comput¬ 
ers  have  full-page  screens,  but  now 
you  can  get  an  80-character  x  57-line 
display  (73  optional)  for  Apple  and 
most  other  computers  with  standard 
RS232  port.  The  Genius  from  Micro 
Display  Systems,  Inc.,  offers  white, 
green,  or  amber  phosphor,  reverse 
and  flashing  video,  128 -character 
ASCII  set  (or  optional  foreign  charac¬ 
ter  sets),  graphics,  19.2K  baud  inter¬ 
face,  and  internal  16K  memory  buffer¬ 
ing  and  screen  memory,  on  an  8-  x 
10.5-inch  display.  You  can  get  100/120 
volts,  60  Hz  for  $1795,  or  shielded 
220/240  volts,  50  Hz  for  $  1950.  (Prices 
are  FOB  Minneapolis,  which,  I  think, 
means  you  have  to  pay  for  shipping 
from  there  to  anywhere  else.)  Reader 
Service  No.  103. 


And  Another  Big  Monitor 

QuadScreen,  from  Quadram,  for 
the  IBM  PC  is  a  17-inch  monochromat¬ 
ic  display  with  160  characters  x  64 
lines,  more  than  five  times  the  screen 
capacity  of  IBM’s  monitor.  Bit-mapped 
graphics  permit  individual  addressing 
of  all  960  x  5 1 2  dots,  while  the  hard¬ 
ware  can  display  any  character  font  in 
any  size  (providing  infinite  user  defin¬ 
able  character  sets).  QuadScreen  has 


its  own  character  set  in  a  5  x  7  matrix, 
while  software  provided  by  Quadram  , 
permits  defining  characters  of  any  size 
or  shape.  Reverse  video  and  smooth 
forward  and  backward  scroll  are 
part  of  the  product.  $1950  gets  you 
the  monitor,  cable,  software,  and  dis¬ 
play  controller  board  that  fits  into  any 
expansion  slot  of  the  PC  and  has  64K 
memory  that  can  be  used  alone  for 
memory  expansion. 

Quadram  also  makes  QuadSpooler, 
a  software  program  that  permits  simul¬ 
taneous  printing  and  spooling,  even 
with  two  printers.  You  designate  from 
2K  to  56K  of  RAM  to  use  as  the 
spooler  buffer.  No  additional  hardware 
is  required,  though  Quadram  would 
like  to  sell  you  one  of  their  Quadboard 
memory  expansion  boards  for  the  PC. 
Buy  one  and  get  QuadSpooler  free,  or 
get  just  the  software  for  $  19.95. 

And  while  I’m  giving  them  space, 
Quadram’s  MicroFazer  has  improved 
since  last  I  mentioned  it.  This  hard¬ 
ware  buffer/spooler  has  a  copy  feature 
that  prints  as  many  additional  copies 
of  the  buffered  information  as  speci¬ 
fied  by  pressing  a  button.  Use  it  with 
any  computer  or  printer,  and  expand 
its  8K  memory  size  up  to  5  12K  (with¬ 
out  using  any  of  the  computer’s  mem¬ 
ory).  Parallel- to- parallel,  parallel- to- 
serial,  serial-to-parallel,  and  serial-to- 
serial  are  all  available,  priced  from 
$169  to  $1395.  Reader  Service  No. 
105. 


And  An  Inexpensive  Amber  Guy 

The  ADP-120A  from  Atlantic 
Data  Products,  a  12-inch,  high- 
resolution,  amber  phosphor  (amber  on 
grey),  16MHz-bandwidth  data  monitor, 
compatible  with  many  micros,  costs 
$169.  Reader  Service  No.  107. 


Rufus  T? 

The  Firefly  battery  pack  (and 
eyeglass  stand)  from  Gamma  Research 
gives  three  to  eight  hours  of  portable 
battery  power  to  Osborne,  Apple, 
IBM,  KayPro,  Franklin  Ace,  et  al.  An 
optional  uninterruptible  power  supply 
(U.P.S.)  protects  micros  from  voltage 
spikes  or  blackouts  by  automatically 
switching  to  the  Firefly  whenever 
sensing  AC  failure  and  functions  as  a 
rapid  (three-  to  four-hour)  Firefly 


charger.  You  get  a  12- volt  DC  power 
cable  to  run  the  computer  or  charge 
the  Firefly  from  your  car’s  cigarette 
lighter,  four  LED  charge  state  moni¬ 
tors,  a  discharge  warning  buzzer,  and  a 
12 -month  warranty.  It  all  comes  in  a 
detachable  (into  two  sections)  6V2-  x 
4V4-  x  91/2-inch  hard  travel  case  with  a 
carrying  strap.  The  Firefly  battery 
pack  reduces  computer  heat  genera¬ 
tion  by  up  to  80%,  they  say,  which  ex¬ 
tends  the  computer’s  life.  The  battery 
pack  is  $229  to  $279,  and  U.P.S.  $99 
to  $109.  And  to  double  battery  power 
time,  they  have  a  booster  pack  for  $169. 
Gamma  Research  also  offers  a  Firefly 
9-inch,  1000-line,  high-resolution, 
green  ($244),  or  amber  ($299)  moni¬ 
tor  in  a  lightweight  travel  case  with 
a  detachable  daylight  glare-reducing 
hood,  that  runs  off  AC,  your  car’s 
cigarette  lighter,  or  (or  course)  the 
Firefly  battery  pack.  Reader  Service 
No.  109. 


Basic  Database  System 
for  CBASIC  and  Other  Bases 

The  Tarbell  Database  System 
from  Elliam  Associates  is  supplied  in 
.COM  files  and  CB80  source  (to  run 
under  CBASIC).  It  supports  up  to  19 
open  files,  with  no  limit  on  numbers 
of  records  or  their  lengths  or  those  of 
field  names.  The  system’s  series  of  pro¬ 
grams  uses  a  common  file  format  for 
random  and  sequential  files,  for  option¬ 
al  index  files,  and  to  chain  from  the 
main  menu  to  other  programs  and 
HELP  files,  set  up  files,  enter  data, 
update  files,  write  reports,  build 
command  files,  copy  files  from  one 
format  structure  to  another,  sort  files, 
print  mailing  labels,  and  personalize 
letters.  A  QUERY  language  interac¬ 
tively  or  from  command  files  defines 
search  area,  scope  of  search,  and 
search  conditions.  You  need  a  48 K  sys- 
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tem.  $100  for  disk  in  most  configura¬ 
tions  and  formats  (specify),  plus  $1.50 
p  &  h  (Californians,  add  sales  tax). 

Reader  Service  No.  115. 


Yeah,  But  Where’s  Ferddy? 

MORTTY  is  a  communications 
program  from  Phillip  Emerson  for  H8, 
H89,  Z89,  and  Z90  computers.  It 
sends  and  receives  ASCII  and  Baudot 
code  at  any  baud  rate  the  equipment 
can  handle,  uses  a  full  screen  and  a 
user-definable  split  screen,  has  a 
type-ahead  buffer,  logs  on  automati¬ 
cally,  allows  the  user  to  define  hand¬ 
ling  of  carriage  return,  line  feed,  and 
control  characters,  echoes  or  not  as 
defined,  uses  full  or  half  duplex, 
automatically  identifies  Morse  code, 
has  advanced  string  storage,  automat¬ 
ically  programs  smart  modems,  print¬ 
ers,  etc.,  and  has  user-definable,  single¬ 
keystroke  functions.  You  need  HDOS 
with  32K  and  a  modem.  You  get  a 
5!4-inch  hard-sectored  disk,  a  60-page 
manual,  and  a  year’s  free  updates,  for 
$100  (Ohio,  add  sales  tax).  Reader 
Service  No.  1 17. 


Alien  Contest 

The  Alien  Group,  who  makes  Voice 
Box  speech  synthesizers  for  Atari  and 
Apple  computers,  would  like  to  give 
away  $6,800  to  the  authors  of  what 
they  judge  to  be  the  best  talking  or 
singing  programs  that  use  (what  else?) 
the  Voice  Box,  in  their  Voice  Box-ing 
Match  Contest  (cute,  cute).  First  prize 
is  $5,000.  Judges  will  be  computer 
game  players  ages  13  to  18.  The  Alien 
Group  also  wants  you  to  know  about 
their  new  Atari  Voice  Box  that  recog¬ 
nizes  phonetic  or  normal  spelling,  has 
an  (apparently)  unlimited  vocabulary 
and  random  sentence  generator,  is  pro¬ 


grammable  from  BASIC  or  assembly 
language,  plugs  directly  into  the  serial 
port,  does  not  blank  the  screen  while 
talking,  is  available  in  16K  cassette  and 
16K  and  32K  disk  versions,  speaks 
with  intonation  or  feeling  (but  they 
don’t  say  if  it  can  do  both  simulta¬ 
neously),  sings  in  key  (that’s  better 
than  I  can  do),  sings  in  three  simulta¬ 
neous  musical  tones,  converts  two  key¬ 
board  rows  into  a  literal  chromatic 
piano  with  a  2!4-octave  range,  pro¬ 
grammatically  handles  glissando,  trem¬ 
olo,  and  vibrato,  comes  with  40  songs 
that  you  can  add  to,  has  a  system  for 
easily  (so  they  say)  creating  and  edit¬ 
ing  words  and  music,  has  educational 
software,  has  two  “talking  heads”  with 
programmable  lip-sync  animation  and 
high-res  color,  and  indues  a  demo. 
$169  for  a  wonderful  product  that  the 
Las  Vegas  Sun  thought  was  the  highlight 
of  COMDEX.  Reader  Service  No.  123. 


Process  Words  for  Less 

Word  processing  software  can  cost 
upwards  of  $500  and  may  not  be 
worth  the  price,  or  cost  under  $100 
and  not  work  worth  beans.  Here’s  one 
from  a  company  known  for  quality 
software  (in  the  games  field  mainly, 
but  they  do  have  a  reputation  to 
maintain)  that  seems  to  offer  a  lot  for 
$69.95.  Bank  Street  Writer  from 
Br^derbund  Software  (“Developed,” 
they  say,  “and  heavily  tested  among 
students  and  young  adults  by  Bank 
Street  College  and  Intentional  Educa¬ 
tions”  —  is  that  the  name  of  a  real 
school?),  for  48K  Apple  11+  or  Apple 
II  with  Applesoft  in  ROM  or  RAM  and 
16-sector  controller  and  for  48K  Atari 
400/800  (and  maybe  1200?)  (re¬ 
quiring  BASIC  cartridge  for  tutorial 
only),  has  global  search  and  replace, 
move  and  unmove,  automatic  centering 
and  indent,  inverse  text  highlighting, 


Load  Bettair  Weeth  Z-Dubber 

Improve  on  the  current  difficulty 
of  loading  cassette  programs  into  the 
Sinclair  ZX81/Timex  1000  with  Z- 


Dubber  from  Bytesize  Computer  Prod¬ 
ucts  or  connect  two  cassette  recorders 
for  making  perfect  backups.  $29.95 
plus  90 shipping.  Reader  Service  No. 

111. 


word  wrap,  disk  storage  and  retrieval 
functions  with  password  protection 
(you  don’t  get  that  on  most  WPs!), 
redefinable  defaults,  and  a  “potent” 
print  format  routine,  including  docu¬ 
ment  chaining,  page  headers,  page 
numbering  at  top  or  bottom,  partial 
printing,  and  format  previewing  before 
printing.  No  special  hardware  is  needed 
and  upper  and  lower  case  are  displayed. 
The  back  of  the  disk  has  a  tutorial, 
and  you  get  a  free  backup  disk  and 
complete  documentation  (I  think  that 
means  a  manual).  Reader  Service  No. 
119. 


“-trix”  Are  Not  Necessarily 
for  Kids 

Quotrix,  the  second  of  Insoft’s 
“-trix”  educational  games  for  the  IBM 
PC  has  players  guess  one  of  700  possi¬ 
ble  famous  quotes  by  following  a  trail 
of  crossword  puzzle  clues,  trivia  ques¬ 
tions,  foreign  words,  and  other  word 
games.  Sounds  like  a  lot  of  fun  for 
$34.95.  Reader  Service  No.  121. 


ET  Enthusiasts 

Join  ETUG,  the  user’s  group  for 
Heath’s  ET/ ETA-3400  microprocessor 
trainer  (but  not  affiliated  with  Heath) 
and  for  those  who  program  the  6800 
and  6809  and  in  tiny  BASIC,  and 
receive  a  quarterly  newsletter  for  $  1 6 
a  year  (US  and  Canada;  $22  elsewhere). 
They’ve  been  around  for  over  a  year. 
LAETUG  for  Los  Angelenos  has  just 
fired  up,  and  meets  at  a  Heathkit  Cen¬ 
ter.  ETUG,  11231  Oak  St„  El  Monte, 
CA  91731;  LAETUG,  c/o  Gilbert 
Murillo,  Heathkit  Electronic  Center, 
2309  S.  Flower,  Los  Angeles,  CA 
90007;  (213)  749-0261  and  443-2237. 


Logo  F or  Atari 

Logo  for  the  Atari  400,  800,  and 
1200XL,  developed  and  manufactured 
for  Atari  by  Logo  Computer  Systems, 
Inc.,  of  Montreal,  will  soon  be  availa¬ 
ble  in  a  16K  cartridge  sold  and  distrib¬ 
uted  by  Atari  for  under  $100.  Reader 
Service  No.  113. 


Learn  Modula-2 

From  the  Father  of  Pascal,  Nick- 
laus  Wirth,  came  Modula-2  ( MODU\nt 
Z/lnguage)  in  1980,  sometimes  called 
“Pascal  for  grownups,”  and  described  in 
understated  fashion  by  Wirth  himself 
this  way:  “The  structure  of  Modula  is 
an  improvement  upon  the  structure  of 
Pascal.”  Yes,  there  was  a  Modula- 1, 
the  developmental  version,  in  1975. 
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Logitech  is  developing  Modula-2,  to¬ 
gether  with  a  fully  symbolic  debugger, 
for  various  8086  CP/M-86  and  MP/M- 
86  environments,  and  would  be  pleased 
if  you  would  contact  them  for  more 
information.  Reader  Service  No.  129. 

And  to  learn  all  about  the  lan¬ 
guage,  Volition  Systems  are  selling  a 
264-page  loose-leaf  format  Modula-2 
User’s  Manual,  accompanied  by  Wirth’s 
48-page  Modula-2  technical  report, 
for  $35.  It  contains  information  about 
standard  library  modules,  utility  library, 
and  implementation  on  UCSD  Pascal, 
and  a  machine-specific  implementa¬ 
tion  guide  with  information  on  librar¬ 
ies,  interrupt  handling,  and  machine- 
level  data  representation.  You  can  also 
buy  Wirth’s  Springer -Verlag  book,  Pro¬ 
gramming  in  Modula-2,  from  them  for 
$16.  Reader  Service  No.  131. 


Tick  TOC 

The  Technology  Opportunity 
Conference  (TOC),  a  worldwide  con¬ 
vergence  of  optical  storage,  videodisk, 
and  computer  technology  sponsored  by 
OPTICAL  MEMORY  NEWSLETTER 
Including  Interactive  Videodisks  and 
Office  of  the  Future  Limited  (heady 


names  indeed!),  will  meet  in  San  Fran¬ 
cisco,  April  5-7;  New  York,  April  26- 
28;  Washington,  June  14- 1 6;  London, 
July  5-7;  Los  Angeles,  July  11-15; 
New  York,  September  12- 16;  Chicago, 
October  10-14;  San  Francisco,  Novem¬ 
ber  8-10;  Kaanapali  (Maui),  November 
29 -December  1 ;  Orlando,  December  5- 
9;  and  Houston,  January  9- 1 3.  Reader 
Service  No.  127. 


Can  Aerobics  for  the  Computer 
Professional  Be  Far  Behind? 

I’ve  got  my  copy  of  Tone  Up  at 
the  Terminals,  “an  exercise  guide  for 
workers  in  automated  offices.”  You 
can  get  yours  too,  free,  from  Verbatim 
Corporation.  Now,  without  leaving  the 
confines  of  my  terminal,  I  can  trim  my 
hips  and  waistline  by  doing  the  Wind¬ 
mill,  release  tension  in  my  hand  and 
wrist  with  the  Wrist  Flex,  do  the  Knee 
Kiss,  and,  to  firm  and  tone  my  legs 
and  (blush)  buttocks,  I  can  do  the 
Derriere  Firmer.  The  12 -page  booklet 
includes  over  20  exercises  that  have 
been  reviewed  and  approved  by  the 
California  Governor’s  Council  on  Well¬ 
ness  and  Physical  Fitness.  Reader  Ser¬ 
vice  No.  133. 
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13  Augusta  Part  III  —  The  Augusta  Compiler 

by  Edward  Mitchell 

Having  discussed  language  definition  and  the  p-code  interpreter  of  Augusta  in 
previous  issues  ( DDJ  Nos.  75  and  77),  Mr.  Mitchell  this  month  begins  discussion 
of  the  recursive -descent  compiler  of  his  unofficial  Ada  subset.  The  listing  of  the 
Augusta  compiler  begins  in  this  issue  and  continues  in  the  July  issue. 

32  A  Fast  Circle  Routine 

by  Daniel  L.  Lee 

The  algorithm  presented  here  draws  complete  circles  accurately  and  quickly,  and 
is  relatively  easy  to  program.  Written  in  assembly  code  for  the  IBM  PC,  the 
routine  can  be  implemented  as  an  IBM  Pascal  procedure. 

38  Enhancing  the  C  Screen  Editor 

by  Alan  D.  Howard 

In  the  January  1982  issue,  Edward  Ream  published  a  Small-C  screen  editor.  Since 
then,  its  popularity  has  continued  to  increase.  Mr.  Howard  provides  enhancements 
to  the  utility  that  should  prove  useful  and  instructive  to  those  wishing  to  expand 
the  editor’s  capability. 

64  Shifts  and  Rotations  on  the  Z80 

by  Ron  Goodman 

Shifts  and  rotations  are  useful  in  a  number  of  programming  contexts.  For  those 
curious  about  this  group  of  instructions  on  the  Z80,  but  unable  to  find  a  satisfac¬ 
tory  description,  Mr.  Goodman’s  discussion  should  prove  enlightening. 

67  The  SBC,  TSX,  and  TXS  Instructions  of  the  6502  and  6800 

by  B.  T.  G.  Tan 

As  one  might  expect,  the  6502  and  6800  CPUs  have  a  number  of  common  instruc¬ 
tions.  Some  of  those,  however,  have  subtle  differences  of  which  the  programmer 
should  be  aware.  Three  such  instructions  are  described  and  compared. 


7  Letters 
7  Editorial 
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items  on  CCS,  CompuPro,  and  more. 
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70  Book  Reviews 
74  CP/M  Exchange 

The  first  in  a  series  of  columns  taking  a  look  at  CP/M  Plus. 

80  16-Bit  Software  Toolbox 
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LETTERS 


Likes  to  C  It  Standard,  Too 

Dear  Dr.  Dobb, 

I  had  to  jump  up  and  cheer  when  I 
read  Richard  Foulk’s  letter  (Standard  De¬ 
viation)  in  DDJ  No.  77.  I  am  a  relative 
newcomer  to  C,  so  when  1  started  seeing 
deviations  from  Kernighan  &  Ritchie,  I 
was  dismayed  but  figured  maybe  they 
knew  what  they  were  doing.  I  am  glad  to 
see  that  someone  else  feels  the  same  way. 

I  bought  Software  Toolworks’s  C/80 
which,  though  not  the  full  implementa¬ 
tion,  does  not  deviate  from  K&R.  My  hat 
is  off  to  Walt  Bilofsky  and  his  crew.  Then 
I  started  transferring  C  User  Group  soft¬ 
ware  from  CP/M  to  HDSO  (Heath)  media 
so  I  could  use  it.  The  hardest  part  was 
translating  the  file-handling  functions  to 
the  K&R  standard  to  which  C/80  adheres. 
(Are  you  listening,  Leor  Zolman?  Please 
bring  BDS  C  back  to  the  K&R  fold.) 

I  always  thought  that  one  of  the 
greatest  advantages  (among  several)  of  C 
over  Pascal  was  the  greater  uniformity 
and  portability  among  versions.  Now, 
that  seems  to  be  fading  away. 

Meanwhile,  take  a  pat  on  the  back 
for  putting  out  a  fine  journal,  and  keep 
those  C  features  coming. 

Sincerely, 

Robert  L.  McClure,  Jr. 

Route  1,  Box  158 

Troy, IL  62294 


CREF  Update 

Dear  People: 

Several  people  have  called  with  ques¬ 
tions  about  “Cross-Reference  Generator 
in  C,”  in  DDJ  No.  68.  The  code  fragment 
at  the  end  of  line  53  of  “cref.c”  is  actually 
the  end  of  line  99.  The  Whitesmith’s  im¬ 
plementation  of  allocQ  takes  two  param¬ 
eters.  The  first  is  the  number  of  bytes  of 
space  to  allocate  and  the  second  is  put  in 
the  first  word  of  the  allocated  space.  All 
linked  lists  in  the  program  use  the  first 
word  in  the  structure  as  a  link.  The  whole 
scheme  works  very  nicely  for  linked  lists 
implemented  this  way. 

The  recursive  implementations  of 
lookupO  and  tree_walk()  are  elegant, 
but  can  use  large  amounts  of  stack  space. 
With  large  files  on  CP/M-80,  this  can 
cause  the  stack  to  overwrite  the  space  al¬ 
located  from  the  heap.  Revised  listings 
are  included  with  this  letter  (see  Figure  1, 
page  9).  Although  the  revised  tree_walk() 
occupies  more  space,  the  capacity  of  the 
revised  program  is  larger.  Algorithm  T  of 
The  Art  of  Computer  Programming,  Vol¬ 
ume  1  is  the  basis  of  the  revised  tree_ 
walk().  The  stack  used  in  Knuth’s  version 
is  implemented  within  the  tree  being  trav¬ 
ersed.  The  left  link  field  is  used  as  a  pointer 
to  the  node  under  it  on  the  stack.  The 
tree  is  destroyed  as  it  is  traversed. 


One  additional  trick:  when  more  files 
are  being  cross  referenced  than  will  fit  on 
a  command  line,  use  #include  statements 
on  the  standard  input. 

Thank  you  to  those  people  who 
called  or  wrote. 

Sincerely, 

Jeff  Taylor 
The  Toolsmith 
139  G  Street,  No.  151 
Davis,  CA  95616 

More  Benchmarks  for  the  PC 

Dear  Sir: 

We  have  performed  a  benchmark  test 
using  Fortran  and  BASIC  on  several  com¬ 
puters.  The  program  was  a  simulation  of 
the  dynamics  of  a  “floating-ring  seal” 
used  in  high-speed  turbomachinery.  This 
is  a  typical  scientific/engineering  appli¬ 
cation,  which  involves  lots  of  number- 
crunching.  The  motivation  here  was  to 
assess  the  speed  of  the  IBM  PC  when  used 
for  engineering  or  scientific  applications, 
and  to  compare  it  with  other  personal 
and  mainframe  computers.  All  tests  were 
performed  in  single -precision.  The  results 
are  shown  in  Figure  2  on  page  9  (numbers 
in  parentheses  indicate  timing  with  Intel 
8087  Math  Coprocessor  and  appropriate 
libraries). 

In  a  further  test,  we  have  run  the 


EDITORIAL 


This  issue  we  welcome  two  new  faces  to  our  ranks.  Bob 
Blum  takes  over  the  CP/M  Exchange  column  this  month 
and  presents  his  first  installment  of  a  series  on  CP/M  Plus. 
He  will  be  exploring  the  features  of  this  new  product  over 
the  next  few  months,  as  well  as  looking  at  how  to  get  more 
from  the  CP/M  2.2  that  you  may  already  have  and  address¬ 
ing  the  usual  mailbag  items.  His  knowledge  of  the  ins  and 
outs  of  CP/M  should  prove  helpful  to  all  of  us. 

The  other  new  face  is  Craig  LaGrow,  our  managing 
editor.  Craig  is  a  science  writer  finishing  his  master’s  degree 
in  journalism  at  Stanford  University.  With  a  strong  back¬ 
ground  in  publishing  and  keen  interest  in  computer  tech¬ 
nology,  he  will  ensure  a  continued  increase  in  the  quality  of 
our  publication. 

*  *  » 

Many  of  you  have  discovered  the  “quick  input”  card 
that  appears  as  an  insert  with  the  reader  service  card.  For 
those  of  you  who  have  not,  let  me  point  it  out  as  an  excel¬ 
lent  way  to  drop  us  a  quick  note.  There  is  no  substitute  for 
a  full  letter  that  can  be  shared,  when  appropriate,  with  the 


readership  at  large;  but  this  card  is  a  fast,  easy  way  to  send 
suggestions  or  comments.  Either  way,  we  love  hearing  from 
you. 

*  *  » 

For  those  who  have  been  wondering,  we  are  planning 
our  annual  Forth  issue.  We  think  you  will  find  it  interest¬ 
ing,  as  always.  Further  down  the  road,  we  would  like  to 
publish  another  telecommunications  issue.  We  have  no  defi¬ 
nite  date  set,  but  are  looking  toward  late  1983.  Those 
interested  in  contributing  to  an  issue  on  this  timely  topic 
should  get  in  touch  with  us. 

On  the  subject  of  general  contributions,  we  would  like 
to  encourage  articles  on  a  wide  range  of  topics.  A  few  that 
come  to  mind  immediately  include  the  68 xx  series  of  CPUs, 
16 -bit  utilities  and  applications,  C  and  Unix.  If  you  have  an 
idea  or  article  in  an  area  that  might  interest  our  readers, 
please  contact  us.  We  will  be  glad  to  discuss  it  with  you. 

—  Reynold  Wiggins, 

Editor 
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Figure  1. 

/*  lookup  -  find  pointer  to  node  for  "naMe"  */ 
struct  node  **lookup(root,  nane) 
register  struct  node  **root; 
register  char  »nane; 

< 

register  int  c; 

while(+root  SX  (c  =  lexcnplnane,  <+root) ->nane,  0))) 
root  =  c  <  0  ?  X(*root)->left  :  X(*root)->right; 
return  root; 

> 

/*  tree_walk  -  walk  a  binary  tree,  doing  ftn  to  ach  node  */ 
tree_walk(root,  ftn) 

register  struct  node  *root; 
int  (*ftn)(); 

{ 

register  struct  node  *stack,  *tnp; 

stack  =  NULL;  /*  stack  initially  enpty  =*/ 
for  (  ;  ;  ) 
if  (root)  { 

t«p  =  root;  /*  nove  to  the  left  */ 

root  =  root->left; 

twp->left  =  stack;  /*  stack  node  */ 

stack  =  tnp; 

> 

else  if  (stack)  -C 
root  =  stack;  /*  pop  stack  ♦/ 
stack  =  stack->left; 

(*ftn) (root) ; 
root  =  root->right; 

} 

else 

break; 

> 


NBS  Methane  properties  package  on  the 
IBM-PC  under  Fortran  3.03.  Execution 
time  was  16.5  seconds  without  the  8087, 
and  2.5  seconds  with  the  8087.  A  time  of 
90  seconds  was  obtained  for  this  program 
on  the  Xerox  820. 

Two  results  deserve  special  comment. 
First,  both  the  original  IBM  release  of 
Microsoft  Fortran  and  the  new  3.03  re¬ 
lease  (presently  under  Beta  Test)  are 
laughably  slow.  Note  that  even  the  3.03 
version  is  practically  as  slow  as  the  8 -bit 
Fortran  of  the  Xerox  820!  This  result  is 
presumably  due  to  Microsoft’s  unwise 
decision  to  write  their  Fortran  in  Pascal 
—  thus  burdening  it  with  all  of  Pascal’s 
inefficiencies.  Even  Microsoft’s  own  BASIC 
compiler  is  faster!  These  Fortrans  are 
therefore  nearly  useless  as  serious  tools  for 
engineering  work,  and  we  can  only  hope 
that  some  enterprising  firm  will  fill  the 
need  for  a  fast  Fortran  for  the  IBM  PC. 

Next,  the  BASIC  compiler  with  the 
8087  does  not  achieve  anything  like  the 
speed  improvement  that  Fortran  does. 
Whether  this  is  due  to  inefficiencies  in  the 
MicroWare  BASIC87  library  or  to  prob¬ 
lems  with  the  BASIC  compiler  itself  is  an 
open  question. 

Sincerely, 

Jim  Glass 
Chris  Landis 

4747  Orion  Avenue,  Apt-  C 
Sherman  Oaks,  CA  91403 


Figure  2. 
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conclusion.  The  CCS  28 10,  or  at  least  our 
elderly  example  of  it,  was  not  kosher  by 
IEEE  696  standards.  It  was  generating 
sINTA,  the  interrupt  acknowledgement, 
much  too  late  in  the  interrupt  cycle  for 
the  CompuPro  board  to  respond  (two 
clocks  later  than  pSYNC,  in  fact).  Oddly 
enough,  it  was  generating  a  perfectly 
good  INTA  status  signal;  however,  this 
signal  is  gated  onto  the  data  bus  along 
with  the  other  simulated  8080  status  bits, 
as  a  compatibility  feature.  The  CompuPro, 
as  you  might  expect,  wouldn’t  have  any¬ 
thing  to  do  with  such  non-IEEE  frippery. 
It  expects  sINTA  to  become  valid,  along 
with  the  other  S-100  status  bits,  when 
pSYNC  comes  up.  We  were  able  to  get 
the  good  INTA  signal  onto  the  sINTA  bus 
line  by  cutting  one  trace  and  soldering  in 
one  jumper  on  the  CCS  board. 

(That  sounds  so  cool.  Just  cut  a  trace, 
solder  a  jumper,  pooh,  no  problem.  Lis¬ 
ten,  no  diamond  cutter  ever  braced  as 
carefully  as  we  did  before  cutting  that 
trace.  And  the  sweat  was  rolling  in 
streams  when  we  powered  up  afterward. 
Would  our  one  and  only  CPU  board  come 
up,  or  would  some  chip  quietly  go  phhht 
and  leave  us  without  a  computer?  And  it 
did  not  come  up!  PANIC!  Then,  looking 
down  from  the  ceding,  we  noticed  that  we 
had  forgotten  to  connect  the  ribbon  cable 
that  runs  from  the  CPU  board  to  the 
CRT.  With  that  hooked  up,  it  ran.  Phew.) 


CompuPro  vs.  Itself 

We  were  using  one  port  of  our  old 
CompuPro  Interfacer  II  board  as  a  source 
of  test  interrupts.  A  Diablo  printer  with  a 
keyboard  was  hooked  to  it,  so  we  could 
produce  a  byte  and  an  interrupt,  while  a 
test  program  reported  the  results  on  the 
CRT.  The  Interfacer  II  generated  inter¬ 
rupts  just  as  expected,  provided  we  en¬ 
abled  only  received-data  interrupts.  If  we 
enabled  transmitted -data  interrupts,  the 
test  program  would  report  a  continuous 
stream  of  them,  indicating  that  the  Inter¬ 
facer  II  was  holding  its  vectored  interrupt 
line  in  a  low  state  all  the  time. 

This  should  not  have  been  the  case. 
According  to  the  schematic,  the  Interfacer 
II  should  reset  its  interrupt  signal  when  it 
sees  sINTA.  We  pulled  the  board  to  see  if 
there  was  a  chip  we  could  change  easily. 
Then  the  problem  became  clear:  the 
board  didn’t  match  the  schematic  that 
came  with  it.  Where  there  should  have 
been  a  chip  U13,  there  was  only  blank 
green  board;  the  inverted  Transmit  Buf¬ 
fer  Empty  signal  from  the  UART  went 
straight  to  the  interrupt  line  and  there 
was  no  reset  circuitry  at  all !  We  never  did 
find  out  whether  we  got  an  early  board 
with  a  late  schematic,  or  vice  versa.  The 
Interfacer  II  isn’t  in  production  anymore, 
and  thank  goodness  we  didn’t  need  its 
interrupts. 


CCS  vs.  The  World 

The  interrupt  we  really  wanted  was 
one  from  the  UART  on  the  2810  CPU 
board,  to  which  the  CRT  is  attached. 
Unfortunately,  CCS  designed  their  board 
assuming  that  only  polled  I/O  would  be 
used.  They  used  the  nice  8250  UART 
(the  IBM  PC  uses  it,  too),  which  has  an 
elaborate  structure  of  prioritized  inter¬ 
rupts  built  into  it.  However,  CCS  left  the 
8250’s  interrupt  pin  unconnected.  We’d 
inquired  about  this  when  first  looking 
into  interrupts  a  year  ago,  and  were  then 
given  instructions  on  how  to  access  the 
8250’s  interrupt  ability.  Here,  for  the 
information  of  those  who  have  a  2810 
CPU  board,  is  how  to  do  it. 

The  8250  generates  an  interrupt  sig¬ 
nal  on  its  pin  30.  This  is  a  positive -going, 
CMOS  signal.  It  has  to  be  buffered  and 
inverted  before  it  can  be  applied  to  the 
S-100  bus.  Near  it  on  the  board  is  U7, 
which  contains  an  unused  XOR  gate 
(make  sure  it  really  is  unused);  this  can 
be  used  as  an  inverter.  We  were  able  to 
connect  U5  (the  8250)  pin  30  to  U7  pin 
12,  and  U7  pin  13  to  U7  pin  14  (tying  it 
to  +5  volts).  Then  we  ran  a  rather  lengthy 
jumper  from  U7  pin  1 1  up  and  over  the 
top  edge  of  the  board,  and  all  the  way 
down  to  the  solder  pad  for  S-100  line  4, 
VIO*. 

It  worked  perfectly  the  first  time. 
During  a  cold  start,  our  BIOS  has  to  prime 
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AUGUSTA,  Part  III 

Recursive  Descent  Compilers 


Compilers  are  computer  programs 
that  perform  language  translation. 
Typical  compilers  translate  a  high- 
level  lanugage,  such  as  BASIC  or  Pascal 
into  the  machine  language  of  the  comput¬ 
er  that  the  program  will  run  on  (see  Fig¬ 
ure  1).  Part  III  of  this  four-part  series  de¬ 
scribes  how  one  type  of  compiler  works. 


Compilers  as  Language  Translators 

The  compiler  doesn’t  have  to  trans¬ 
late  directly  into  machine  code.  Some 
compilers  output  assembly  language  that 
must  be  assembled  later.  Others  output 
an  intermediate  language  that,  in  turn,  is 
compiled  to  machine  code  or  interpreted 
at  run-time.  There  are  even  compilers 
that  translate  from  one  high-level  language 
into  another.  For  example,  the  RATFOR 
language  is  compiled  into  Fortran. 

Augusta  programs  are  compiled  into 
an  intermediate  language  called  “pseudo¬ 
code”  (“p-code”  for  short).  In  effect,  the 
p-codes  are  the  machine  language  of  a 
hypothetical  or  pseudo-machine.  The 
compiler  uses  a  technique  known  as  “re¬ 
cursive  descent  parsing”  to  perform  the 
translation.  Compilers,  and  in  particular 
recursive-descent  compilers,  are  the  sub¬ 
ject  of  this  article.  Included  in  this  part  is 
the  first  half  of  the  Augusta  compiler 
source  listing  (see  page  20).  Part  IV  con¬ 
tains  the  rest  of  the  compiler  listing  and 
a  detailed  description  of  the  compiler’s 
operation. 


The  Compilation  Process 

Compilation  is  divided  into  three 
steps:  (1)  lexical  analysis,  (2)  syntactic 
analysis,  and  (3)  semantic  analysis  and 
code  generation.  Some  compilers  make 
several  passes  through  the  source  program, 
perhaps  performing  one  of  the  above 
steps  on  each  pass.  Augusta  is  a  one-pass 


by  Edward  Mitchell 


Edward  Mitchell,  Box  390145,  Mountain 
View,  CA  94039. 

This  series  Copyright  ©  1983  by  Edward 
Mitchell.  The  Augusta  Compiler  is  Copy¬ 
right  ©  1983  by  Computer  Linguistics. 
“Augusta”  is  a  trademark  of  Computer 
Linguistics.  “Ada”  is  a  registered  trade¬ 
mark  of  the  U.S.  Department  of  Defense. 


compiler,  so  all  three  steps  occur  simul¬ 
taneously. 

Lexical  analysis  carves  the  source  pro¬ 
gram  into  logical  entities  called  “tokens.” 
To  the  computer,  a  source  file  is  just  a 
long  sequence  of  characters.  The  lexical 
analyzer  breaks  the  characters  into  recog¬ 
nizable  groups  such  as  “IF”,  “THEN”, 
“(’’  “ALPHA”,  and  so  on. 

Syntactic  analysis  or  “parsing” 
ensures  that  the  tokens  returned  by  the 
lexical  analyzer  appear  in  the  correct 
order.  The  syntax  diagrams  presented  in 
Part  I  of  this  series  describes  the  order  of 
tokens  for  all  valid  Augusta  programs. 

When  the  syntax  analyzer  recognizes 
a  valid  sequence  of  tokens,  the  compiler 
outputs  p-codes.  During  compilation, 
these  three  steps  are  intermingled.  When 
the  syntax  analyzer  needs  a  new  token,  it 
calls  the  lexical  analyzer.  When  enough 
tokens  have  been  read  so  that  the  parser 
can  recognize  a  statement  or  phrase  of 
the  language,  then  the  code  is  generated. 


Lexical  Analysis 

The  lexical  analyzer  reads  the  source 
program  character  by  character.  Once  it 
recognizes  a  valid  sequence  of  characters, 
it  returns  the  entire  group  as  a  token. 

The  classical  approach  to  designing  a 
lexical  analyzer  is  to  draw  a  state  diagram. 
The  state  diagram  is  really  just  a  special 
kind  of  flowchart  where  circles  replace 
the  usual  rectangular  boxes  and  diamonds. 
The  diagram  describes  what  the  lexical 
analyzer  should  do  for  each  character 
that  it  sees.  Figure  2  (page  14)  shows  a 
diagram  to  separate  digits  from  letters  in 
a  stream  of  characters  like  “ABC5347 
PWX943ZW1F0”.  That  input  would  pro¬ 
duce  the  following  sequence  of  tokens: 
“ABC”,  “5347”,  “PWX”,  “943”,  “ZW”, 
“1”,  “F”,  and  “0”. 

Each  circle  inside  the  diagram  repre¬ 
sents  a  state.  The  diagram  begins  with 
state  1.  On  seeing  the  letter  “A”,  the  lexi¬ 
cal  analyzer  reads  a  new  character  from 


(a) 


(b) 


LAO  4  ;  push 

;  address 
;  A 

LDO  6  ;  push  B 
LDO  4  ;  push  A 
LDCI  3  ;  push  3 
MPI  ;  3  *  A 
ADI  ;  +  B 
STO  ;  result 


Figure  1 . 

(a)  A  compiler  translates  a  high-level  language  into  the  machine  language  of  the 
computer  that  the  program  will  run  on.  (b)  The  translation  of  a  simple  Augusta 
statement  into  p-codes. 


— ^ 

A :  =  B  +  A  *  3 ;  > 

COMPILER 

_ 
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the  input  and  jumps  to  state  3.  The  aster¬ 
isk  (“*”)  indicates  that  a  character  is 
read  before  entering  the  new  state. 

The  analyzer  remains  in  state  3  as 
long  as  it  continues  to  see  an  alphabetic 
character.  Upon  reading  “5”  from  the  in¬ 
put,  the  analyzer  jumps  to  state  4.  At  this 
point,  it  has  identified  the  first  complete 
token  “ABC”.  Returning  to  state  1,  the 
analyzer  is  still  looking  at  a  “5”  so  it 
jumps  to  state  2  and  processes  the  digit 
characters.  Listing  1  (page  17)  shows  how 
the  state  diagram  can  be  converted  to  a 
BASIC  program. 

A  compiler,  such  as  Augusta,  must 
recognize  a  large  number  of  tokens  — 
many  more  than  just  letters  and  numbers 
—  for  example,  all  of  the  arithmetic  opera¬ 
tors,  “+”,  “*”,  and  plus  all 

of  the  punctuation  symbols  like  “(”, 
“)”,  and  Some  symbols  are 

harder  than  others  to  recognize.  For 
example,  “/”  by  itself  is  the  division  sym¬ 
bol.  But  if  it  is  immediately  followed  by 
“=”,  as  in  it  becomes  the  “not 

equal”  relational  operator.  Similarly, 
some  tokens  can  be  quite  lengthy.  Take 
the  character  string,  for  example.  It  be¬ 
gins  with  a  double  quote  (“)  followed  by 
a  large  number  of  characters  that  are  ter¬ 
minated  by  a  trailing  quote. 

Just  as  flowcharts  are  unnecessary 
for  coding  many  programs,  state  diagrams 
are  not  really  needed  for  many  lexical 
analyzers.  Instead ,  a  practiced  programmer 
can  directly  code  an  appropriate  analyzer 
fairly  quickly.  To  wit,  Augusta’s  lexical 
analyzer  was  written  in  a  single  evening 
and  appears  in  lines  1280  through  1775 
of  Listing  2  (page  20). 

The  lexical  analysis  stage  of  the  com¬ 
piler  will  often  do  additional  work  to  aid 
the  rest  of  the  compilation  process.  Num¬ 
bers  are  converted  from  their  character 
representation  (e.g.,  “197”)  into  an  inter¬ 
nal  numeric  form  (e.g.,  TN=197,  where 
TN  is  a  variable).  All  identifiers  (any  to¬ 
ken  beginning  with  an  alphabetic  charac¬ 
ter)  are  looked  up  in  the  keyword  table. 
If  the  identifier  is  a  keyword  like  “AND” 
“PROCEDURE”,  or  “ELSE”,  then  the 
lexical  analyzer  marks  the  token  as  a  key¬ 
word.  Unquoted  lower  case  letters  are 
converted  to  upper  case. 

In  most  compilers,  the  lexical  analy¬ 
zer  is  a  subroutine.  At  each  call,  it  returns 
the  next  token  from  the  program  source. 

Syntax  Analysis 

The  syntax  analyzer  or  “parser” 
checks  that  the  tokens  appear  in  the 
proper  order.  The  “proper  order”  is  de¬ 
termined  by  the  language’s  syntax  which 
is  the  set  of  rules  that  defines  the  lan¬ 
guage.  The  syntax  diagrams  in  Part  I 
(January  1983)  of  this  series  show  what 
valid  Augusta  statements  look  like. 

How  does  syntax  analysis  work? 
There  are  actually  several  techniques  for 
parsing  a  computer  program.  Augusta 


uses  a  method  called  recursive-descent 
parsing,  which  is  a  variation  of  “top- 
down”  parsing.  The  names  “recursive 
descent”  and  “top  down”  come  from 
how  the  parser  builds  a  parse  tree.  (You 
don’t  need  to  understand  the  theory  in 
great  detail.  However,  it’s  convenient  for 
following  the  basic  operation  of  the  par¬ 
ser.  I’ll  keep  this  theoretical  section  to  a 
minimum.) 

A  tree  is  a  special  type  of  data  struc¬ 
ture  that  is  normally  depicted  upside 
down  as  in  Figure  3  (page  15).  This  im¬ 
plies  that  the  “root”  is  at  the  top  of 
the  tree  and  the  “branches”  are  at  the 
bottom.  Top-down  parsing  is  so  named 
because  it  produces  a  tree-like  structure 
from  the  top  and  going  downwards  as  it 
parses  a  statement.  Compare  the  syntax 
diagrams  in  Figure  4  (page  16)  to  the 
parse  tree  in  Figure  3(b)  (page  15).  The 
parse  tree  represents  the  path  that  the 
compiler  follows  through  the  syntax 
diagrams  as  it  parses  an  expression. 

To  see  how  syntax  analysis  works, 
we’ll  construct  a  parser  for  the  simplified 
expressions  described  by  the  syntax  dia¬ 
grams  in  Figure  4  (page  16).  These  dia¬ 
grams  recognize  the  algebraic  hierarchy  of 
operations:  and  “/”  come  before 

“+”  and 

The  syntax  diagrams  are  recursive 
because  one  of  the  definitions  is  defined 
in  terms  of  itself.  EXPR  is  defined  using 
SE;  SE  is  defined  using  FACTOR;  and  in 
the  case  of  a  parenthesized  expression, 
FACTOR  is  defined  using  EXPR. 


The  diagrams  can  be  translated  into  a 
set  of  procedure  calls.  A  simple  implemen¬ 
tation  of  the  parser  written  in  Augusta  is 
shown  in  Listing  3  (page  27).  Procedure 
GETTOKEN  (not  shown  in  Listing  3) 
reads  a  single  token  of  input  and  places  it 
in  the  global  variable  TOKEN.  TOKEN  is 
a  character  containing  “C”  if  a  constant 
was  read,  “I”  if  an  identifier  was  read,  or 
one  of  the  punctuation  symbols  “(”, 

“)”,  7”,  “+”, 

To  parse  the  expression,  3  *(5+6), 
GETTOKEN  reads  the  “3”.  EXPR  calls 
SE  to  evaluate  a  “simple  expression.”  SE, 
in  turn,  calls  FACTOR.  Seeing  a  constant 
“C”,  FACTOR  reads  the  next  token  and 
returns  to  SE.  Since  the  token  “*”  is  not 
one  of  “+”  or  control  returns  to 
EXPR.  But  “*”  is  recognized  by  EXPR, 
so  EXPR  reads  the  next  token,  a  left 
parenthesis  “(”,  and  calls  SE  again.  SE 
calls  FACTOR  where  the  parenthesis  is 
handled.  FACTOR  scans  past  the  “(”  by 
calling  GETTOKEN  and  calls  EXPR  to 
evaluate  the  subexpression.  After  return¬ 
ing  from  EXPR,  FACTOR  sees  the  right 
parenthesis  “  )”  and  returns  to  SE,  which 
returns  to  EXPR. 


Semantic  Analysis 

Statements  that  are  syntactically 
valid  may  still  not  make  sense.  Variable 
identifiers  such  as  A  and  B  can  be  multi¬ 
plied  together  if  and  only  if  A  and  B  are 
numeric  variables.  If  A  and  B  are  strings, 
then  the  statement  is  meaningless.  For 
example, 


Figure  2. 

A  simple  state  diagram  to  separate  letters  from  digits.  See  text  for  details. 
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(1)  A  :=  “String  1”; 

(2)  B  :=  “String  2”; 

(3)  C  :=  A  *  B; 

Statement  3  is  syntactically  correct  but 
semantically  wrong. 

Semantic  analysis  attempts  to  infer 
meaning  from  the  statement;  e.g.,  C  is  to 
be  assigned  the  quantity  of  A  multiplied 
by  B.  Once  the  compiler  understands  the 
statement,  it  can  generate  the  correspond¬ 
ing  p-code  translation. 

Syntax  analysis  only  cares  about 
finding  the  correct  tokens,  such  as  a  con¬ 
stant,  an  identifier,  a  keyword,  or  so  on. 
Semantic  analysis,  on  the  other  hand. 


examines  the  value  of  the  tokens.  For 
example,  the  identifier  “ALPHA”  must 
be  looked  up  in  a  symbol  table  to  see  if 
it  is  defined.  If  it  is  defined,  then  the 
compiler  must  determine  that  it  can  be 
used  correctly  in  the  current  context. 

Code  Generation 

Augusta  generates  code  as  it  does  the 
parsing.  An  example,  using  the  simple 
expression  parser,  shows  how  this  is  done. 
Let 

X  :=  5  *  4; 

be  a  simple  assignment  statement.  The 


compiler,  upon  seeing  an  identifier  fol¬ 
lowed  by  begins  parsing  the  assign¬ 
ment  statement.  The  symbol  “X”  is 
looked  up  in  the  symbol  table,  which 
tells  the  compiler  that  X  is  an  integer  vari¬ 
able  stored  at  global  offset  10.  Augusta 
generates 

LDA  10  ;  Load  address  of  variable  X 

The  compiler  next  scans  across  the  expres¬ 
sion.  But  note  that  because  Augusta  gen¬ 
erates  code  for  a  stack  machine,  both 
operands  (the  “5”  and  the  “4”)  must  be 
pushed  on  the  stack  before  performing 
the  multiplication.  This  means  that  the 
following  sequence  of  p-codes  will  be 
created : 

LDCI  5  ;  Load  constant  5  on  to  the 
;  stack 

LDCI  4  ;  Load  constant  4  on  to  the 
;  stack 

MPI  ;  Pop  top  2  words,  multiply 
;  together,  and  push  result 

Finally,  the  top  of  stack  value  is  stored  at 
X,  by  emitting  the  instruction 

STO  ;  Store  top  of  stack  value  in- 
;  to  the  address  contained  in 
;  the  next  word  on  the  stack 

Listing  4  (page  28)  shows  the  simple  ex¬ 
pression  parser  modified  to  generate 
p-codes. 

Two  new  procedures,  EMITBYTE 
and  EMITWORD,  have  been  created.  The 
parsing  routines  call  EMITBYTE  and 
EMITWORD  when  they  need  to  output 
;  p-codes  or  p-code  parameters.  For  exam¬ 
ple,  the  LDCI  opcode  is  output  with  the 
following  calls: 

EMITBYTE  ( 1 )  ;  -  LDCI  p-code 
;  value 

EMITWORD  (5)  ;  —  constants  fol- 
;  lows  LDCI 

Code  Generated  for  FOR  Loops 

The  previous  section  gave  an  over¬ 
view  of  the  code  generation  scheme.  We 
will  now  look  at  some  specific  statements 
and  see  what  the  corresponding  p-code 
translation  looks  like. 

The  FOR  loop  has  the  form 

FOR  <Identifier>  IN 

<  Starting  Value  >  .  . 

<  Ending  Value  > 

LOOP 

< Sequence  of  Statements> 

END  LOOP; 

For  example, 

FOR  I  IN  1  ..  10 
LOOP 

PUTINT(I); 

NEWLINE; 

END  LOOP; 

prints  the  integers  1  throught  10. 

For  the  loop  above,  the  compiler 
must  emit  code  to  set  I:=l  at  the  begin¬ 
ning  of  the  loop  to  check  to  determine 
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if  I  is  greater  than  1 0  and  to  increment  I 
each  time  the  loop  is  executed.  Listing  5 
(page  29)  shows  sample  code  for  the  loop 
shown  above. 

When  the  FJP  instruction  at  (1)  in 
Listing  5  is  emitted,  the  compiler  does 
not  yet  know  where  the  program  should 
jump  to.  Until  the  code  for  the  enclosed 
sequence  of  statements  is  generated,  the 
compiler  doesn’t  know  how  many  bytes 
the  FJP  instruction  should  jump  past. 
Instead,  it  must  remember  where  the  FJP 
instruction  is  located,  generate  the  re¬ 
maining  code,  and  then  go  back  and  fix 
the  FJP  instruction  so  that  it  will  jump  to 
the  correct  location.  This  technique  is 
called  “back  patching”  and  is  used  ex¬ 
tensively  when  compiling  long  sequences 
of  IF-THEN-ELSEIF  and  CASE  state¬ 
ments. 

The  WHILE  Statement 

The  WHILE  statement  is  translated 
into  a  conditional  test,  followed  by  the 
enclosed  statements  and  ending  with  a 
jump  back  to  the  conditional  test.  Listing 
6(b)  (pages  28  and  29)  shows  the  code 
produced  for  WHILE  statement  shown  in 
6(a)  (page  28). 

IF-THEN  Statements 

Listing  7(a)  (page  29)  shows  sample 


code  for  a  simple  IF-THEN-ELSE  state¬ 
ment.  Back  patching  is  done  for  all  the 
forward  jump  instructions,  which  in¬ 
cludes  both  the  FJP  and  UJP  p-codes  in 
Listing  7(b)  (page  29). 

“Short  circuit”  boolean  expressions, 
whether  used  in  assignment  statement  or 
as  part  of  an  IF-THEN  test,  use  the  FJP 
instruction  to  jump  over  portions  of  the 
expression  code.  Listing  8(b)  (page  30) 
shows  the  code  generated  for  the  state¬ 
ments  in  8  (a)  (page  30). 

The  CASE  Statement 

The  CASE  statement  is  unusual  in 
that  it  uses  the  XJP  (indirect  jump)  op¬ 
code  to  branch  to  the  appropriate  section 
of  code.  XJP  is  a  seven-byte  opcode, 
having  the  format 

XJP  wl,w2,  w3 

where  wl,  w2,  and  w3  are  16-bit  words. 
XJP  uses  the  value  on  the  top  of  the 
stack  as  an  index  into  a  jump  table  that 
appears  after  the  code  for  each  of  the 
cases,  wl  and  w2  are  the  minimum  and 
the  maximum  case  selections,  respectively. 
For  example,  in  a  CASE  statement  like 
CASE  I  IS 

WHEN  7  =>  ... 

WHEN  1 1  =>  ... 


WHEN  19  =>  ... 

WHEN  23  =>  ... 

END  CASE; 

the  minimum  selector,  wl,  is  7,  and  the 
maximum  selector,  w2,  is  23.  Word  w3 
is  the  offset  to  the  indirect  jump  table. 
Listing  9  (page  30)  shows  the  basic  format 
for  the  case  statement. 

The  jump  table  has  the  following 
format, 

-*  UJP  instruction 

address  of  OTHERS  condition 
address  of  case  w  1 
address  of  case  wl  +  1 
address  of  case  w  1 H  2 


address  of  case  w2-  1 
address  of  case  w2 

For  the  CASE  statement  shown  previously, 
with  selectors  7,  11,  19,  and  23,  an  entry 
is  made  in  the  jump  table  corresponding 
to  each  selector.  But  the  jump  table  has 
sixteen  entries  (maximum  selector  minus 
minimum  selector  or  23  -  7)  and  so  only 
four  entries  are  accounted  for.  All  other, 
unused  selectors  are  filled  with  the  address 
of  the  UJP  instruction  at  the  beginning 
of  the  table.  Then,  when  a  case  value  for 
I  is  not  one  of  7,  11,  19,  or  23,  the 
program  does  an  automatic  jump  to  the 
OTHERS  clause.  The  first  entry  in  the 
table  is  the  address  of  the  code  to  handle 
the  OTHERS  condition.  In  the  event  that 
there  is  no  OTHERS  clause,  this  entry 
simply  jumps  to  the  first  instruction  after 
the  jump  table. 


In  the  July  Issue 

Part  IV  contains  the  final  half  of  the 
Augusta  compiler  source  listing.  It  con¬ 
cludes  with  some  personal  comments  on 
the  subjects  of  Ada,  the  rationale  for 
creating  Augusta,  the  DoD,  and  Microsoft 
BASIC. 

(Listing  One  below) 

(Listings  2  through  9  on  pages 
20  through  30) 


Figure  4. 

Syntax  diagrams  for  a  simple  expression  parser. 
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Augusta  Part  III 

Listing  One 

10  'SIMPLE  LEXICAL  ANALYZER 
20  ’  • 

30  D I GITS*="0 123456789" 

40  ALF'HA*=  "  ABCDEFGH I J KLMNOF'QRSTUVW X  Y Z  " 

50  INPUT  "ENTER  STRING:  "  ,  S* 

60  P=1  ’  P  POINTS  TO  NEXT  CHAR  TO  READ 

70  GOSUB  800  ’  READ  CHAR  INTO  CH* 

100  ’ STATE  1  -  DECIDE  IF  ALPHABETIC  OR  DIGIT 
110  IF  INSTR  (DIGITS*, CHS)  THEN  GOSUB  800:  GOTO  200 
120  IF  I NSTR  ( ALPHAS , CH* )  THEN  GOSUB  800:  GOTO  300 
130  GOTO  500 

200  ’STATE  2  --  READ  IN  DIGITS 

210  IF  INSTR (DIGITS*, CH*)  THEN  GOSUB  800:  GOTO  200 
220  GOTO  400 

300  ’STATE  3  -  READ  IN  ALPHABETIC  CHARS 

310  IF  INSTR (ALPHA*, CH*>  THEN  GOSUB  800:  GOTO  300 

320  GOTO  400 

400  ’ STATE  4  -  OUTPUT  THE  EXTRACTED  TOKEN 
410  PRINT  TOKEN* 

420  TOKEN*=" " 

430  GOTO  100 

500  ’STATE  5  -  INVALID  CHARACTER  STOPS 
510  STOP 

800  ’READ  CHARACTER  OF  INPUT 

810  IF  P >LEN ( S* )  THEN  CH*=" ." :  RETURN 

820  TOKEN*=TOKEN*+CH*  ’  ACCUMULATE  A  TOKEN 

830  CH*=M I D* ( S* , P , 1 )  ’  GET  NEXT  CHARACTER 

840  P=P+1 

850  RETURN  End  Listing  One 

(Listing  Two  begins  on  page  20) 
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(Continued  on  page  28,  column  2)  I  (Listing  Eight  begins  on  page  30) 


A  Fast  Circle  Routine 


In  some  instances  it  is  necessary  to  draw 
partial  circles  or  arcs  and  at  other  times 
complete  circles  are  required.  The  algo¬ 
rithm  presented  here  draws  complete  cir¬ 
cles  accurately  and  quickly  and  is  relatively 
simple  to  program.  The  routine  is  written 
for  the  IBM  Personal  Computer  using 
IBM’s  Macro  Assembler,  and  can  be  imple¬ 
mented  as  an  IBM  Pascal  procedure. 

The  Algorithm 

Circle  algorithms  generally  use  a  trans¬ 
formation  from  polar  to  rectangular  co¬ 
ordinates  by  the  following  relationships: 

X  =  R  cosine(A) 

Y  =  R  sine(A) 

where  the  (X,Y)  coordinates  produce  the 
locus  of  points  for  the  given  radius  R  as 
the  angle  A  varies  from  0  to  2  pi  radians. 
This  method  requires  trigonometric  rou¬ 
tines  to  compute  sine  and  cosine  values  at 
least  for  the  start  and  end  points  and  for 
an  angular  increment. 

A  simpler  method  which  does  not  re¬ 
quire  sine  and  cosine  values  is  obtained 
by  elementary  calculus,  which  can  be  used 
to  show  that  dX/dY=-tangent(A)=-Y/X. 
Also,  dY/dX  =  -cotangent(A)=-X/Y.  In 
other  words,  the  change  in  X,  given  a  small 
change  in  Y,  is  simply  the  negative  of  the 
ratio  of  Y  to  X.  Similarly,  the  change  in 
Y,  given  a  small  change  in  X,  is  simply 
the  negative  of  the  ratio  of  X  to  Y. 

Given  these  relationships,  the  circle 
procedure  is  straightforward.  For  simplic¬ 
ity  it  will  be  assumed  that  the  circle  center 
is  at  the  origin  of  our  coordinate  system. 
It  is  not  difficult  to  adjust  for  a  change  in 
origin. 

The  first  point  plotted  is  chosen  as 
Y=R  and  X  =  0,  where  R  is  the  radius 
measured  in  screen  column  units.  Y  is 
incremented  by  one  unit  and  X  is  decre¬ 
mented  by  Y/X  units  and  the  point  plotted. 
This  process  is  continued  until  Y/X=  1.  At 
that  point  (which  corresponds  to  a  45 
degree  angle),  we  switch  over  to  decreasing 
X  by  one  unit  and  increasing  Y  by  X/Y 


by  Daniel  L.  Lee 


Daniel  L.  Lee,  1401  E.  55th  Street,  Apt. 
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units.  The  process  is  continued  until  X/Y 
equals  0,  i.e.,  when  X  is  decremented  to  0. 
At  that  point  an  arc  from  0  to  90  degrees 
has  been  drawn.  The  complete  circle  can 
be  obtained  by  using  the  symmetry  of  the 
circle  to  compute  the  corresponding 
points  in  each  of  the  three  remaining  cir¬ 
cle  quadrants  as  we  trace  out  the  arc  from 
0  to  90  degrees. 

The  switch  over  when  Y/X  equals  1  is 
required  because  the  tangent  will  approach 
infinity  as  the  angle  approaches  90  degrees, 
and  overflow  will  occur  somewhere  prior 
to  that  point. 

To  actually  implement  the  algorithm, 
we  have  to  adjust  for  the  origin  located  at 
the  top  left-hand  corner  of  the  video 
screen.  Also  we  have  to  take  into  account 
the  aspect  ratio  of  the  screen.  When  plot¬ 
ting  0  to  45  degrees,  the  X  value  must  be 
multiplied  by  the  inverse  of  the  aspect 
ratio,  and  when  plotting  from  45  to  90 
degrees,  the  Y  value  must  be  multiplied 
by  the  aspect  ratio.  Assuming  a  screen 
aspect  ratio  of  4/3,  the  aspect  ratio  to 
produce  a  circle  in  medium-resolution 
graphics  is  5/6  and  is  5/12  for  high- 
resolution  graphics. 

The  Assembly  Routine 

The  routine  incorporates  the  elements 
of  the  algorithm  just  described.  It  is  also 
necessary  to  scale  the  computations  by 
some  factor  to  retain  numerical  accuracy, 
and  then  to  rescale  to  obtain  the  points 
to  plot.  A  factor  of  1000  gives  sufficient 
accuracy  for  the  PC’s  high-resolution 
mode. 

As  mentioned,  the  circle  routine  can 
be  implemented  as  a  Pascal  procedure. 
Listing  1  (page  35)  is  the  circle  routine 
and  Listing  2  (page  37)  is  a  simple  calling 
routine  which  generates  an  internal  calling 
sequence  as  used  by  IBM  Pascal. 

Pascal  sets  up  a  frame  on  the  stack 
for  an  active  procedure  which  is  invoked 
by  a  FAR  call.  First,  the  calling  program 
pushes  the  procedure  arguments  from 
left  to  right  onto  the  stack.  Then  the 
caller’s  segment  address  and  offset  are 
pushed  onto  the  stack.  When  the  proce¬ 
dure  receives  control,  it  should  first  save 
the  caller’s  base  pointer  by  pushing  BP 
onto  the  stack.  Then  the  BP  register  is 
set  equal  to  the  SP  register  (stack  point¬ 
er)  and  the  procedure  can  then  reference 
the  arguments  by  adding  six  bytes  to  the 
BP  register  —  four  for  the  caller’s  return 
address  and  two  for  the  caller’s  base 
pointer  which  has  been  pushed  onto  the 


stack.  Thus,  assuming  integer  value  argu¬ 
ments,  the  first  variable  on  the  stack  can 
be  addressed  by  BP+6,  the  second  by 
BP+8,  and  so  on. 

To  return,  the  procedure  must  restore 
the  caller’s  base  pointer  in  BP  and  the  SP 
register  must  be  restored  by  a  RET  x, 
where  x  is  the  number  of  bytes  on  the 
stack  occupied  by  the  arguments  which 
were  passed. 

Note  that  the  IBM-supplied  BIOS 
routine  is  used  to  write  the  points  to 
screen.  That  is  accomplished  by  storing 
12  in  the  AH  register,  the  X  coordinate 
in  the  CX  register,  the  Y  coordinate  in  the 
DX  register,  and  then  issuing  an  INT  10H 
instruction.  In  this  routine,  the  INT  10H 
instruction  is  defined  as  the  MACRO, 
BIOSCALL,  the  expansion  of  which  is 
denoted  by  “+”  in  the  listing. 

(Listing  begins  on  page  35) 
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Fast  Circle  Plot  (Text  begins  on  page  32) 

Listing  One 
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Enhancing  the 
C  Screen  Editor 


In  the  January  1982  issue  of  Dr. 
Dobb’s  we  presented  Edward  Ream’s 
popular  Small -C  screen  editor.  Readers 
received  a  fine  editor  which,  at  the  same 
time,  was  an  excellent  candidate  for  ex¬ 
tension  and  modification.  Alan  Howard 
has  provided  us  with  an  extensive  set  of 
enhancements.  Those  who  wish  to  im¬ 
plement  changes  in  the  original  editor 
should  find  guidance  and  inspiration  from 
Mr.  Howard’s  work. 

Mr.  Howard  has  chosen  a  modular 
approach  to  the  problem  and  his  changes 
should  be  easy  to  implement.  Mr.  Ream 
himself  has  attacked  the  situation  by  sig¬ 
nificant  revision  of  the  entire  editor.  We 
will  be  publishing  Mr.  Ream’s  revision, 
called  RED,  in  the  near  future.  Compari¬ 
son  of  these  two  approaches  should  pro¬ 
vide  insight  into  programming  techniques 
and  implementation  tradeoffs,  and  we 
feel  fortunate  to  be  able  to  publish  both 
pieces  of  work. 

While  the  January  and  May  1982 
back  issues  are  no  longer  available  (the 
bound  volume  containing  them  should  be 
out  later  this  year),  we  understand  the 
original  editor  may  still  be  obtained  from 
a  variety  of  sources,  including  several 
computer  bulletin  boards.  Edward  Ream 
still  distributes  it  himself  for  $50  on  8- 
inch,  CP/M  diskettes,  and  can  be  reached 
at  1850  Summit  Avenue,  Madison,  W1 
53705.  A  BDS  C  version  may  be  obtained 
from  The  C  User’s  Group,  Box  287, 
Yates  Center,  KS  66783  (which  sells  it 
for  $8  in  a  variety  of  formats)  and  Steve 
Passe’s  C  rode  computer  bulletin  board 
(contact  i  e  C  Users’  group  for  details). 

At  the  beginning  of  Edward  Ream’s 
article  introducing  his  Small-C 
Screen  Editor  in  Dr.  Dobb’s  Jour¬ 
nal  (No.  63,  January  1982),  he  asked 
whether  our  present  editor  lacked  flexi¬ 
bility,  transportability,  and  extensibility. 
Although  my  mainstay  editor  has  been 
PIE  from  Software  Toolworks,  I  have 
often  been  annoyed  at  its  inability  to  edit 
large  files  or  to  make  major  structural 
changes  in  text.  On  the  other  hand, 
Ream’s  editor  as  presented  did  not  go 
much  beyond  PIE  and  seemed  clumsy  in 
its  Edit  mode.  It  did,  however,  encourage 
adapting  it  to  fit  individual  needs  since  it 
was  presented  in  source  code.  Thus, 


by  Alan.  D.  Howard 

Alan  D.  Howard,  Route  3,  Box  680, 
Crozet,  VA  22932. 


after  several  nights  of  typing  and  several 
more  nights  of  debugging,  I  had  the  C 
editor  up  and  running  (those  of  you  who 
want  to  join  me  doing  it  the  hard  way,  be 
sure  to  note  the  bug  fixes  in  the  May 
issue,  No.  67).  I  have  been  modifying  the 
editor  during  the  last  few  months  and  it 
has  evolved  to  the  point  that  I  feel  some 
of  Dr.  Dobb’s  readers  may  be  interested. 
The  changes  are  of  several  types: 

(1)  Extensions  to  the  file-handling 
and  buffer  management  to  permit  editing 
large  files,  extracting  parts  of  the  text  to 
the  write  file,  and  moving  and  copying 
portions  of  the  text  within  the  file. 

(2)  Changing  the  edit  mode  opera¬ 
tion  to  recognize  special  keys  on  the  H19 
Terminal  or  H89  Computer  instead  of 
single-letter  commands.  As  a  bonus,  the 
editor  now  assumes  exchange  mode  for 
any  other  typed  key.  The  code  can  be  easi¬ 
ly  modified  for  other  terminal  protocols. 

(3)  Addition  of  a  few  new  commands 
to  the  edit-mode  and  some  changes  in 
rules  of  operation. 

(4)  Slight  modifications  to  allow 
modular  compilation  using  the  Software 
Toolworks  C/80  compiler. 

(5)  Enhancements  to  improve  the 
speed  of  response  in  edit  mode  and  during 
search  and  replace  operations. 

These  enhancements  are  discussed 
below  as  explanations  for  the  listing  that 
accompanies  this  article.  Only  those  varia¬ 
bles,  declarations,  and  functions  that  have 
been  changed  from  the  original  listing  are 
listed.  A  documentation  file  is  included  in 
the  listing  which  summarizes  the  expanded 
features  and  all  commands. 

Changes  to  File  Handling  and 
Command -Mode  Operation 

Most  of  the  changes  to  the  command¬ 
mode  are  concerned  with  adding  flexibili¬ 
ty  to  file  handling  and  major  buffer  alter¬ 
ations.  Separate  read  and  write  files  are 
now  maintained,  with  load  <filename> 
specifying  the  read  file  name,  clearing  the 
buffer,  reading  the  file,  and  closing  the 
read  file  if  it  all  fits  in  the  buffer.  Other¬ 
wise  as  much  as  fits  is  read  in,  and  the 
read  file  remains  open.  If  a  filename  is 
specified  in  the  command  line  when  the 
editor  is  loaded,  the  filename  is  automat¬ 
ically  passed  to  the  load  command.  The 
open  <  filename  >  command  opens  the 
read  file  without  clearing  the  buffer  or 
reading  anything  in.  More  from  the  read 
file  can  be  added  to  the  buffer  with  either 


the  rest  or  read  <n>  commands.  Rest 
reads  in  as  much  more  as  possible  and 
gives  the  option  of  clearing  the  buffer, 
but  read  <n>  reads  only  <n  >  more  lines 
without  clearing  the  buffer.  The  write  file 
is  specified  by  name  <  filename >  for  a 
new  file,  or  delname  <filename>  for  writ¬ 
ing  over  an  existing  file  (this  replaces  the 
resave  command).  Rename  <filename> 
closes  the  existing  write  file  and  opens 
a  new  one.  Write  <n>  writes  <n> 
lines  from  the  buffer  to  the  write  file,  de¬ 
leting  those  lines.  To  balance  the  existing 
append  <filename>  command,  an  extract 
<from  to>  command  has  been  added  to 
write  the  indicated  line  range  to  the  write 
file  without  deleting  those  lines  from  the 
buffer.  Finally,  to  allow  flexibility,  the 
read  and  write  files  can  be  closed  by 
closeread  and  closewrite. 

Major  structural  changes  in  the  file 
can  now  be  made  using  the  copy  <from 
to  n>  and  move  <from  to  n>  com¬ 
mands,  which  take  n  lines  from  <from> 
and  copy  them  to  before  line  <to>.  In 
addition,  move  deletes  the  <n>  lines  at 
<from>.  For  speed,  these  routines  open 
up  the  new  space,  and  then  do  the  copying 
or  moving.  No  move  or  copy  is  allowed 
if  there  is  not  room  in  the  buffer.  If  buf¬ 
fer  space  is  tight,  or  if  the  move  or  copy 
is  to  a  part  of  the  file  not  currently  in 
memory,  then  use  the  extract  and  append 
commands,  which  use  the  disk  as  a  buffer. 

Because  tabs  are  treated  as  ordinary 
characters,  showtab  has  been  included  to 
allow  tabs  to  be  shown  in  reverse  video. 
This  mode  is  reset  by  hidetab  (the  default 
mode)  where  tabs  are  just  blanks. 

The  following  command-mode  com¬ 
mands  are  unaltered  from  the  original: 
append,  change,  clear,  delete,  dos,  find, 
g,  list,  search,  and  tabs. 

Changes  to  Edit  and  Insert  Modes 

The  most  important  change  to  the 
edit  mode  is  the  replacement  of  the  single¬ 
letter  commands  by  escape- character 
sequences  generated  by  the  special  keys 
on  the  H19/H89  keyboard.  Similar  keys, 
but  with  different  escape  sequences,  are 
found  on  many  other  terminals  and  com¬ 
puters.  This  allows  default  use  of  the  ex¬ 
change  mode  (replacing  contents  of  cur¬ 
sor  position  with  the  typed  keystroke) 
for  normal  keys,  including  the  space  bar. 
The  exchange  mode  has  been  speeded  up 
considerably  to  allow  rapid  typing.  Most 
special  characters  and  edit  mode  com¬ 
mands  retain  their  original  functions  (see 
the  documentation  portion  of  the  listing 
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for  details),  but  two  new  commands  have 
been  created  for  the  edit  mode:  the 
HOME  key  moves  alternately  to  the  top 
and  bottom  line  of  the  screen,  and  the 
ERASE  key  erases  from  the  current  cur¬ 
sor  position  to  the  end  of  the  line.  More 
subtle  changes  have  also  been  made.  The 
RETURN  key  moves  to  the  beginning  of 
the  next  line  in  edit  mode,  but  acts  as  the 
insert  down  key  in  the  insert  mode.  Both 
the  DC  and  DELETE  keys  delete  the 
character  at  the  cursor,  but  BACKSPACE 
deletes  the  character  to  the  left  of  the 
cursor,  the  same  as  the  original  delete 
character  special  key.  The  only  commands 
remaining  as  control  codes  are  split  and 
join.  There  is  some  room  for  expansion: 
three  keys  are  currently  assigned  to  force 
command  mode,  but  could  be  reassigned. 
Note  that  the  ESC  key  must  be  pressed 
twice  to  be  recognized,  because  it  is  also 
issued  by  the  special  character  codes  of 
the  keyboard.  My  choice  of  key  assign¬ 
ments  and  features  has  admittedly  been 
influenced  by  the  PIE  editor. 

Implementation  Details 

I’d  like  to  start  out  with  an  unsolicited 
endorsement  of  the  Software  Toolworks 
C/80  Compiler,  now  in  version  2.0  and 
incorporating  almost  all  of  the  C  language. 
It’s  a  descendent  of  Small-C  and  is  inex¬ 
pensive,  fast,  and  powerful.  Its  salient 
feature  in  the  context  of  the  editor  is 
support  for  modular  compilation  using 
Microsoft  M80  and  L80.  Since  the  editor 
is  broken  into  nine  fairly  independent 
modules,  changes  can  be  made  in  one 
without  having  to  recompile  everything. 
Also,  SID  can  be  used  for  debugging  using 
global  variable  and  function  names.  The 
disadvantage  is  that  variable  and  function 
names  must  be  distinct  at  six  characters’ 
length.  This  has  necessitated  renaming 
several  functions  in  the  editor,  as  listed  in 
Figure  1  (page  42).  (I  have  not  listed 
each  occurrence  of  the  altered  names  in 
the  listing;  I  leave  that  as  a  test  of  the 
capabilities  of  your  present  editor.)  Also, 
to  force  the  main  buffer  to  be  at  the  end 
of  the  program,  the  short  program 
MBUFFER.MAC  must  be  assembled  by 
M80  and  be  the  last  module  linked  (after 
the  C/80  CLIBRARY  module). 

Most  details  of  the  changes  are  ex¬ 
plained  in  the  listing  on  page  43.  The 
functions  that  are  completely  unchanged 
are  not  included,  but  a  note  indicates  then- 
position.  In  general,  I  have  listed  the  entire 
function  if  there  has  been  any  change. 

Concluding  Remarks 

This  editor  is  a  very  useful  addition 
to  my  stable  of  inexpensive  editors,  and  is 
particularly  suited  to  editing  large  files, 
interleaving  text  from  other  files,  and 
breaking  up  a  file  or  portions  of  a  file 
into  smaller  pieces.  It  doesn’t  do  every¬ 
thing,  and  reading  and  writing  to  files  are 
considerably  slower  than  for  editors  writ¬ 


ten  in  assembly  language.  I  suggest  those 
with  H89’s  go  through  the  bothersome 
task  of  reassembling  their  BIOS  with  the 
type-ahead  buffer  option  so  that  rapid 
typing  will  not  lose  characters. 

When  I  move  on  to  my  next  system, 
I  will  feel  secure  that  I  have  its  first  editor 
waiting  in  the  wings,  and  it  won’t  cost  me 
twice  as  much  as  my  previous  editor  for 
the  same  features.  The  modifications  to 
the  editor  are  in  the  public  domain,  and  a 
somewhat  earlier  version  has  been  submit¬ 
ted  to  the  SIG/M  User  Group  (Amateur 
Computer  Group  of  New  Jersey,  Box  97, 
Iselin,  NJ  08830). 

(Figure  1  on  page  42) 
(Listing  begins  on  page  43) 
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/#  new?  set  three  arguments  %/  whi  le <  (  «pos>1  )  14 &  (  !  buf  attoe ( 

Set3args(  ergs  r  val  1 » val2»  vail)  char  *args?  int  fcvallf  *val2f#val3»  if  (buf  ue( )  !  =0K)  <1 

return(ERR) 


54 


Dr.  Dobb’s  Journal,  Number  79,  May  1983 

261 


Dr.  Dobb’s  Journal.  Number  79.  Mav  1983 
262 


55 


fintoutch(c:»col )  char  cr  int  col?  x*outxSet(> 

s  tf=outw£(et  ( ) 


58 


Dr.  Dobb’s  Journal,  Number  79,  May  1983 

263 


/*****  out. del  In  <  )  unchanged  *♦***/  f  mtsout  ( s  1 25) 


(Continued  on  page  60,  column  2)  I  (Continued  on  page  62,  column  1) 


62 

266 


Dr.  Dobb’s  Journal,  Number  79,  May  1983 


if  < ( lens th=buf length ( f rom»n> )==0)< 


/#*##*  ED9.C  functions  unchanged  ***##/ 


05 1 ,2  I  / Continued  on  page  62,  column  2) 


Shifts  and  Rotations 
on  the  Z80 


The  shift  and  rotation  commands  on 
the  Z80  are  powerful  commands. 
They  allow  simple  division  and  mul¬ 
tiplication.  Along  with  the  BIT  command, 
they  provide  powerful  control  over  the 
eight  bits  in  each  byte.  But  for  all  the 
brilliant  applications,  how  does  one  know 
which  specific  type  of  shift  or  rotation 
one  needs?  Since  I  could  not  find  an 
explanation  of  the  discrete  differences 
between  these  commands,  I  compiled  the 
following  with  a  little  research  and  exper¬ 
imentation.  Hopefully  it  will  prove  help¬ 
ful  when  employing  these  powerful  com¬ 
mands  in  any  future  assembly/machine 
language  endeavors.  Note  that  whenever 
the  command  is  “xxx  r,”  the  “r”  refers 
to  any  single,  unpaired  Z80  register  other 
than  “F”  and  a  couple  of  other  things. 
Thus,  r  can  be  A,  B,  C,  D,  E,  H,  L,  (HL), 
(IX  +  d),  or  (IY+d). 

(1)  RR  r  —  Rotate  Right  thru  Carry. 

This  command  moves  each  bit  in  the  cho¬ 
sen  register  to  the  right.  The  bit  in  position 
0  goes  to  the  carry  flag,  and  the  carry  flag 
status  is  placed  into  bit  position  7.  This 
command  is  valuable  because  it  allows  for 
examining  each  individual  bit’s  status. 
Each  time  RR  r  is  performed,  the  next 
bit  is  placed  in  the  carry,  allowing  appro¬ 
priate  action  —  e.g.,  “JR  C,BlTON.”  An 
example  of  this  command  may  be  found 
in  the  program  in  Figure  1  at  right. 

(2)  RLC  r  —  Rotate  Left  Circular. 

This  moves  each  bit  in  the  specified  regis¬ 
ter  to  the  left.  The  bit  in  position  7  of  the 
register  is  put  in  position  0.  The  use  of 
this  rotate  is  probably  less  common.  It  can 
multiply  a  number  by  two  if  the  result  is 
less  than  255.  If  the  result  is  greater  than 
255,  the  status  of  bit  8  (256th’s  place, 
which  is  really  the  ninth  bit  and  so  nor¬ 
mally  not  there)  will  be  stored  in  bit 
position  0.  Bit  position  0  will  hence  equal 
1  if  the  result  is  greater  than  255,  and  0  if 
the  result  is  less  than  or  equal  to  255.  Fig¬ 
ure  2  at  right  shows  a  program  using 
RLC.  Notice  that  it  uses  the  “A”  register 
but  it  could  use  any  of  the  “r”  values. 

(3)  RL  r  —  Rotate  Left  thru  Carry. 

This  moves  each  bit  to  the  left,  but  the 
bit  in  position  7  goes  to  the  carry  flag  and 
the  carry  flag  status  is  put  into  bit  0.  This 
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command  can  be  used  like  RR  r,  except 
that  this  rotates  the  other  direction.  If  it 
is  used  for  multiplication  and  the  result  is 
greater  than  255,  the  carry  flag  will  be  set. 

(4)  RRC  r  —  Rotate  Right  Circular. 

This  moves  each  bit  to  the  right.  The  bit 
in  position  0  of  the  byte  is  put  into  posi¬ 
tion  7.  This  command  works  like  RLC  r 
except  it  rotates  the  other  direction 
and  hence  it  divides. 

(5)  SLA  r  —  Shift  Left  Arithmetic. 

With  this  command  all  of  the  bits  are 
shifted  to  the  left.  The  status  of  bit  0  is 
always  0  after  this  shift  is  used,  and  bit  7 
is  lost.  This  is  best  described  in  Table  1 
on  page  66.  This  command  has  a  some¬ 
what  more  useful  multiply  ability  for 
most  applications.  It  multiplies  by  two 
and  leaves  0  at  bit  position  0.  After  multi¬ 
plying  any  binary  number  by  two,  bit 
position  0  should  equal  0  because  the 
answer  is  even. 

(6)  SRA  r  —  Shift  Right  Arithmetic. 

All  of  the  bits  are  shifted  to  the  right.  The 
status  of  bit  7  remains  unchanged,  but  bit 
0  is  lost.  Although  this  command  can  be 
used  for  division,  the  main  problem  is 
that  it  leaves  bit  7  on  and  hence  it  will 


give  an  inaccurate  result  if  the  number  to 
be  divided  is  greater  than  127.  There  may 
be  some  practical  reason  for  leaving  bit 
7  on,  but  I  am  unaware  of  it. 

(7)  SRL  r  —  Shift  Right  Logical. 

This  command  is  very  similar  to  SRA  r. 
All  of  the  bits  are  again  shifted  to  the 
right,  and  bit  0  is  lost.  But  with  this  com¬ 
mand,  the  status  of  bit  7  is  always  set  to 
0  after  a  shift.  This  makes  this  command 
far  more  practical  for  division  than 
SRAr.  Unlike  SRAr,  which  will  only  give 
an  accurate  result  if  the  number  being 
divided  is  less  than  128,  this  will  give 
an  accurate  answer  if  the  number  to 
be  divided  is  less  than  or  equal  to  255 
(which  will  always  be  the  case  if  it  is 
being  stored  in  an  8 -bit  register). 

Table  1  shows  how  each  of  the  com¬ 
mands  operates.  Each  one  is  performed 
several  times  on  a  number  to  provide  easy 
visualization  of  the  command’s  results. 

(Table  1 .  on  page  66) 
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00100 

;  THIS  PROGRAM  WILL  PRINT  THE  BINARY  REPRESENTATION 

00110 

;  OF  THE  ‘A’  REGISTER  ON  A  TRS-80  SCREEN  AT 

00120 

;  SCREEN  LOCATION  3C00H  (15360  DECIMAL). 

00130 

00140 

PRINT 

LD 

B,8 

00150 

LD 

HL.3C07H 

00160 

LOOP 

RRA 

00170 

LD 

A, 48 

00180 

JR 

NC.ZERO 

00190 

LD 

A, 49 

00200 

ZERO 

LD 

(HL),A 

00210 

DEC 

HL 

00220 

DJNZ 

LOOP 

00230 

RET 

Figure  1. 

00100 

;  PROGRAM  TO  MULTIPLY  ‘A’  BY  2.  PRODUCT  MUST  BE 

00110 

;  LESS  THAN  OR  EQUAL  TO  128. 

00120 

;  THE  COMMAND  RLCA  DOES  SAME  THING  AS  RLC  A 

00130 

00140 

MULT  2  RLC 

A 

00150 

RES 

0,A 

00160 

RET 

Figure  2. 

RR 

THE  BYTE 

CARRY 

RRC 

THE  BYTE 

SRA 

THE  BYTE 

SRL  THE  BYTE 

11111111 
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00000001 

10100000 

10100000 

01111111 
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10000000 

1 1010000 

01010000 

10  111111 
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01000000 

11101000 

00101000 

11011111 

1 

00100000 

11110100 

00010100 

1110  1111 
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00010000 

111110  10 

00001010 

11110  111 
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00001000 

11111101 

00000101 

111110  11 

1 

00000100 

11111110 

00000010 

11111101 

1 

00000010 

11111111 

00  0  0  0  0  0  1 

11111110 

1 

00000001 

11111111 

00000000 

11111111 

0 

10000000 

11111111 

RL 

THE  BYTE 

CARRY 

RLC 

THE  BYTE 

SLA 

THE  BYTE 

00000001 

0 

00000001 

11111111 

00000010 

0 

00000010 

11111110 

00000100 

0 

00000100 

11111100 

00001000 

0 

00001000 

11111000 

00010000 

0 

00010000 

11110000 

00100000 

0 

00100000 

1 1 100000 

0  1  0  00000 

0 

01000000 

1 1000000 

1  0  0  0  0  0  0  0 

0 

10000000 

10000000 

00000000 

1 

00000001 

00000000 

00000001 

0 

00000010 

00000000 

Table  1. 
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SBC,  TSX  and  TXS 

Instructions  of  the  6800  and  6502 


The  6800  and  6502  microprocessors 
have  very  similar  architectures  and 
instruction  sets.  The  common  in¬ 
structions  of  these  two  microprocessors 
have  been  listed  elsewhere,1,2  and  the 
purpose  of  this  note  is  to  draw  attention 
to  three  common  instructions  which  have 
subtle  but  important  differences  in  their 
operation  on  the  two  MPUs.  These  are: 

SBC  Subtract  with  carry  (on  the  6800 
the  mnemonic  is  followed  by  A 
or  B  indicating  the  accumulator 
concerned) 

TSX  Transfer  stack  pointer  to  index 
register 

TXS  Transfer  index  register  to  stack 
pointer 

SBC 

The  differences  in  the  carry-bit  oper¬ 
ation  for  the  subtract  instruction  of  the 
1802  and  Z80  microprocessors  have  been 
pointed  out  by  Merrin.3  Likewise,  the  dif¬ 
ferences  in  SBC  between  the  6800  and 
6502  are  due  to  the  different  ways  in 
which  the  two  MPUs  utilize  the  carry  bit 
of  their  status  registers.  Though  SBC  is 
nominally  described  as  subtract  with 
carry,  a  better  description  would  be  sub¬ 
tract  with  borrow. 

The  add  with  carry  instruction,  ADC, 
is  also  common  to  the  6800  and  6502, 
and  functions  identically  on  them.  The 
operation  can  be  represented  as 

A  +  M  +  C 

where  A  is  the  contents  of  the  accumula¬ 
tor,  M  the  operand,  and  C  the  carry  bit  of 
the  status  register.  The  result  is  put  into 
the  accumulator  and  the  resulting  carry 
bit  is  stored  in  C.  The  resulting  carry  bit 
will  be  1  only  if  the  result  exceeds  255. 
In  the  case  of  the  6502,  ADC  is  the  only 
addition  instruction,  and  if  an  add  with¬ 
out  carry  is  required,  the  carry  bit  must 
be  cleared  first  by  preceding  ADC  with 
CLC  (clear  carry  bit). 

To  understand  the  SBC  instruction 
better,  let  us  assume  that  the  status  regis¬ 
ters  of  both  MPUs  have  another  status 
bit  called  the  borrow  bit.  The  operation 
of  the  SBC  instruction  can  then  be  repre¬ 
sented  as 

A-M-B 
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where  B  is  the  borrow  bit.  B,  as  well  as 
M,  is  subtracted  from  A,  and  the  result  is 
put  into  the  accumulator.  The  borrow 
bit  resulting  from  the  operation  will  be 
stored  in  B.  The  resulting  borrow  bit  will 
be  1  only  if  the  absolute  value  of  (M  +  B) 
is  greater  than  that  of  A.  The  result  of  the 
operation  goes  into  the  accumulator.  The 
function  of  B  is  to  facilitate  multi-byte 
subtraction  when  borrow  bits  from  one 
8 -bit  subtraction  have  to  be  utilized  in 
the  subtraction  for  the  next  higher  8-bits. 

If  the  subtraction  without  borrow  is 
required,  the  borrow  bit  must  be  cleared 
before  SBC.  We  can  invent  two  pseudo¬ 
instructions 

SEB  Set  borrow  bit 

CLB  Clear  borrow  bit 

to  enable  us  to  manipulate  B,  analogously 
to  SEC  and  CLC  for  C.  Hence  we  must 
precede  SBC  with  CLB  for  a  subtract 
without  borrow. 

In  the  6800  and  6502  MPUs,  there  is 
no  separate  borrow  bit  in  their  status  reg¬ 
isters.  The  carry  bit  C  does  double  duty  as 
a  borrow  bit,  so  that  it  is  better  described 
as  a  carry/borrow  bit.  In  the  6800,  the 
borrow  bit  is  identical  with  the  carry  bit, 
so  that  the  SBC  operation  can  be  repre¬ 
sented  as 

A  -  M  -C 

and  the  borrow  bit  generated  is  directly 
put  into  C.  The  instructions  SEB  and 
CLB  correspond  to  SEC  and  CLC  respec¬ 
tively. 

In  the  6502,  the  borrow  bit  is  the 
inverse  of  the  carry  bit,  so  that  SBC  is 

A-M-C 

and  the  borrow  bit  generated  is  inverted 
before  being  put  into  C.  Hence  the  SEB 
instruction  corresponds  to  CLC  and  CLB 
to  SEC.  For  a  subtraction  without  bor¬ 


row,  SBC  would  have  to  be  preceded  by 
SEC. 

The  difference  is  thus  best  under¬ 
stood  by  considering  the  borrow  bit  B  as 
entirely  separate  from  C  and  then  taking 
B  =  C  for  the  6800  and  B  =  C  for  the 
6502.  The  implementation  of  the  borrow 
bit  for  the  6502  is  different  from  the 
6800  in  order  that  arithmetic  operations 
on  the  6502  would  give  more  consistent 
results  for  C. 

For  example,  the  arithmetic  opera¬ 
tions  5-3  and  5  +  (-3),  using  the  two’s 
complement  in  the  second  operation, 
would  lead  to  different  values  for  C  in 
the  case  of  the  6800.  These  operations 
would  give  the  same  values  for  C  in  the 
case  of  the  6502,  since  its  borrow  bit  is 
the  inverse  of  C.  In  Table  1  (below),  the 
two  operations  are  listed  for  each  MPU. 
showing  the  corresponding  values  of  the 
accumulator  and  the  carry  bit  after  each 
instruction.  These  operations  were  verified 
on  SWTPC  6800  and  Apple  II  microcom¬ 
puters.  The  6809,  which  is  the  upgraded 
version  of  the  6800,  appears  to  implement 
the  borrow  bit  in  a  similar  manner  to  the 
6800,  that  is  with  the  borrow  bit  the 
same  as  the  carry  bit. 

TSX  and  TXS 

The  transfer  instructions  between  the 
stack  pointer  SP  and  index  register  X, 
TSX  and  TXS  are  common  to  both  6800 
and  6502  but  have  important  differences. 
In  both  MPUs,  the  current  value  of  SP 
points  to  the  location  one  address  below 
the  bottom  of  the  stack.  These  registers 
are  16 -bits  long  in  the  6800,  and  8 -bits 
long  in  the  6502. 

In  the  6800,  TSX  increments  the 
contents  of  SP  by  1  and  then  transfers 
them  to  X.  The  reason  for  this  appears  to 
be  to  make  X  point  to  the  actual  bottom 


6800 

6502 

ACCA 

c 

B=C 

ACC 

C 

B=C 

LDAA  #$05 

05 

D 

D 

LDA  #$05 

05 

D 

D 

CLC 

05 

0 

0 

SEC 

05 

1 

0 

SBCA  #$03 

02 

0 

0 

SBC  #$03 

02 

1 

0 

LDAA  #$05 

05 

D 

D 

LDA  #$05 

05 

D 

D 

CLC 

05 

0 

0 

CLC 

05 

0 

1 

ADCA  #$FD 

02 

1 

1 

ADC  #$FD 

02 

1 

0 

Table  1. 

5  minus  3  subtraction  operations  for  6800  and  6502.  D  indicates  don’t  care  state. 
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of  the  stack.  This  is  presumably  for  cases 
when  indexing  operations  on  the  stack 
are  to  be  carried  out.  Conversely,  TXS 
decrements  the  contents  of  X  by  1  before 
transferring  them  to  SP,  so  that  if  X 
pointed  to  the  bottom  of  the  stack,  SP 
would  then  point  to  the  next  location 
below  the  bottom. 

The  6502’s  TSX  and  TXS  instructions 
do  not  perform  the  increment  and  decre¬ 
ment  operations;  they  are  just  straight¬ 
forward  data  transfer  instructions.  Why  is 
this  so?  SP  is  an  8 -bit  register,  and  its 
contents  ZZ  are  always  interpreted  as 
pointing  to  the  page  1  of  memory,  $01ZZ. 
The  effective  address  in  indexed  addres¬ 
sing  is  found  by  adding  the  8-bit  contents 
of  X  to  the  operand.  In  the  zero-page  in¬ 
dexed  mode,  the  effective  address  is  in 
page  zero;  in  the  absolute  indexed  mode, 
the  page  of  the  effective  address  depends 
on  the  16-bit  operand. 

Because  of  these  complications,  the 
TSX  and  TXS  instructions  of  the  6502  do 
not  appear  to  be  intended  to  facilitate 
indexed  operations  on  the  stack,  as  the 
transfers  are  effected  without  increment¬ 
ing  and  decrementing.  The  primary  func¬ 
tion  of  TSX  and  TXS  appears  to  be  to 
effect  data  transfer  to  and  from  SP  via  X. 
This  is  in  fact  the  only  way  to  do  so, 
since  the  6502  lacks  LDS  (load  to  stack 
pointer)  and  STS  (store  from  stack  point¬ 
er)  instructions.  These  instructions  are 
part  of  the  6800’s  instruction  set. 

The  6809  MPU,  which  is  the  upgraded 
version  of  the  6800,  has  the  instructions 
TFR  S,X  and  TFR  X,S  which  are  equiva¬ 
lent  to  TSX  and  TXS,  respectively.  In  the 
6809,  the  stack  pointer  points  to  the  bot¬ 
tom  of  the  stack,  and  not  to  the  location 
below  the  bottom  as  in  the  case  of  the 
6800.  Thus,  the  two  transfer  instructions 
do  not  perform  an  increment  or  decre¬ 
ment  before  the  transfer,  and  are  more 
like  their  6502  equivalents,  but  for  a 
quite  different  reason. 

Conclusions 

The  6800  and  6502  MPUs  are  so 
similar  that  it  is  worth  looking  at  both 
together  when  studying  one  of  them.  I 
have  taken  this  approach  in  my  micro¬ 
processor  teaching,  using  a  MPU  model 
consisting  of  the  common  features  of  the 
two  MPUs.2  This  MPU  model  has  one  8- 
bit  accumulator,  one  8 -bit  index  register, 
one  16-bit  program  counter,  one  8-bit 
stack  pointer,  and  one  8 -bit  status  regis¬ 
ter.  It  has  the  same  six  addressing  modes 
of  the  6800,  except  that  indexed  addres¬ 
sing  is  restricted  to  the  zero  page  only.  The 
instruction  set  is  made  up  of  the  43  in¬ 
structions  common  to  both  6800  and 
6502.  These  instructions  include  SBC, 
TSX,  and  TXS,  and  it  is  important  that 
those  using  both  the  6800  and  6502  un¬ 
derstand  the  small  but  important  differ¬ 
ences  in  these  instructions. 


Program  FLIP 

commen  t 

$ 

PROGRAM  FLIP 

This 

program  flips  from  the  c o  1  o r - a d a p t e r  to  the  mono c h r ome - a d a p t e r 

a  nd 

back  aga in  The 

program  has  no  stack  segment  so  that  it  can  be 

converted  into  a  COM 

file  This  generates  an  error  upon  linking  which 

should  be  ignored 

Simson  L  Garfinkel, 

1983 

1 

data 

s  e  gme  n  t  at  4  0  h 

o  r  g 

6 

equip 

db  ? 

data 

ends 

c  s  e  q 

segment  para  'code' 

o  r  g 

1  OOh 

;I  want  to  use  this  as  a  COM  file 

start 

p  r  o  c 

far 

assume  c s  c s e g , s s  :  c s e g  ,  d s  data 

mo  v 

a  s  ,  c  s 

mo  v 

s  s  ,  a  x 

mo  v 

sp  ,  stacke 

, ge  t  end  of  stack 

push 

d  s 

lor 

a  x  ,  a  x 

push 

a  x 

.save  how  to  get  home 

mo  v 

a  x , da  t  a 

;use  ds  to  reference  segement  at  0 

mo  v 

d  s  ,  a  x 

mo  v 

ah  ,  equip 

and 

ah , 30h 

cmp 

ah , 30h 

•check  to  see  if  we  are  running  mono  or  color 

j  ne 

mono 

imp 

color 

, we  are  in  mono  -  switch  to  color 

mo  no 

o  r 

equip, 30h 

■switch  to  monochrome  interface 

mo  v 

ax  ,  2 

i  n  t 

1  Oh 
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SOFTWARE  REVIEW 


ZAS  Z8000 

Software  Development  Package 
By  Western  Wares,  P.O.  Box  C,  Norwood, 

CO  81423 
CP/M  Version  $395 
ISIS  Version  $495 
Reviewed  by  Terry  R.  Dettmann 

What  is  there  to  say  about  an  assem¬ 
bler?  It  either  assembles  good  code  or  it 
doesn’t.  ZAS  assembles  functioning  Z8000 
code  (consistent  with  your  own  ability  to 
design  such  code  in  the  first  place! ). 

Is  there  any  more  to  say?  Should  a  re¬ 
view  really  continue  after  this  point?  Well 
in  some  cases  I’d  say  no  it  shouldn’t,  but 
in  this  case  there  is  more  to  the  package 
that  is  important  to  know  about.  More 
that  the  package  can  do.  What  more  should 
I  say?  Well,  let’s  look  and  see  just  what 
you  get  when  you  get  the  assembler 
package. 

First  there’s  the  ZAS  assembler  itself. 
It  is  a  “full-featured,  relocatable  cross 
assembler  for  the  Z8000.”  Its  instruction 
mnemonics  are  compatible  with  those 
developed  by  Zilog.  Comparing  it  to 
Matosian’s  book  on  the  Z8000  (SYBEX), 
it  didn’t  always  agree  on  how  some  things 
should  be  done,  but  it  was  easy  to  learn. 

ZAS  also  includes  the  “extended”  in¬ 
structions  needed  for  some  Z8000  units.  It 
wasn’t  hard  to  use.  It  generated  good  code 
for  the  Z8000,  but  has  only  really  been 
tested  on  limited  development  systems.  I 
haven’t  tried  to  code  a  large  project. 

ZAS  is  a  two-pass  assembler.  It  has  all 
the  standard  things  you  expect  to  find  in  a 
full-featured  assembler  such  as  condition¬ 
al  assembly,  named  sections,  segmented 
and  non-segmented  addressing  support, 
nested  include  files,  up-to-64-character 
symbol  names,  and  standard  directives 
and  pseudo-ops. 

After  the  assembler  comes  the  ZLK 
task  builder.  ZLK  is  a  flexible  linking 
program  that  allows  complicated  processes 
to  be  set  up  as  overlays  and  so  forth, 
while  allowing  the  programmer  complete 
control  over  memory  placement  of  the 
code  modules 

ZLD  is  an  absolute  file  loader  pro¬ 
gram.  Its  basic  purpose  is  to  load  a  Z8000 
module  under  CP/M  or  ISIS  so  that  it 
can  be  executed  with  the  ZEX  run-time 
monitor.  ZEX  allows  the  user’s  system 
to  provide  run-time  support  as  needed  for 
a  Z8000  task.  ZEX  allows  bus-switching 
between  8080-type  CPUs  and  Z8000 
CPUs,  as  on  the  IEEE  696  (S-100)  bus 
or  the  Intel  Multibus.  It  even  allows  the 
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program  to  make  CP/M  or  ISIS  calls  as 
needed. 

In  this  kind  of  mode,  the  Z8000 
CPU  is  acting  as  if  it  were  a  temporary 
bus  master  device  and  the  8080  CPU  is 
the  bus  master.  All  I/O  is  handled  by  the 
bus  master  (the  8080)  through  the  CP/M 
system. 

ZEX  is  configured  by  the  user  to  the 
particular  environment.  Detailed  instruc¬ 
tions  are  provided  to  allow  proper  con¬ 
figuration  by  anyone  with  reasonable 
technical  knowledge.  This  isn’t  a  system 
for  the  novice  Z8000  programmer,  but 
it  is  a  useful  tool  for  serious  system 
development. 


Editor’s  note:  Just  before  press  time,  we 
were  informed  that  version  2.0  of  the  ZAS 
Z-8000  package  had  been  released.  Some 
of  the  enhancements  will  be  of  particular 
interest  to  those  familiar  with  older  ver¬ 
sions  of  ZAS.  The  following  new  features 
were  added  in  the  new  version,  which  was 
received  too  late  for  review  in  this  issue: 
new  macro  pseudo-operations  (MACRO, 
IRP,  IRPC,  EXITM,  REPT,  ENDM, 
LOCAL),  other  new  pseudo -ops  (DZ  - 
define  zero,  DA  -  define  address),  new 
directives  ($BASE  -  set  default  number 
base;  $LIST,  MACON,  MACOFF  -  con¬ 
trol  macro  expansion  listing),  new  com¬ 
parison  opertors  taking  string  or  numerical 
arguments,  extended  instruction  enhance¬ 
ment,  mo-e  symbol  table  space  and  faster 
searching  of  tables,  more  flexibility  for 
input,  command-line  switches  specified 
by  -  or  /,  and  ZAS  and  ZLK  now  use  the 
same  command-line  syntax. 


6809  Cross  Assembler 
Available  from  Avocet  Systems  Inc., 
804  South  State  Street,  Dover, 
DE  19901 
$200 

Reviewed  by  Terry  R.  Dettmann 

It  wasn’t  long  ago  that  I  came  up 
with  an  acute  need  for  a  6809  assembler. 
Not  just  a  small  one  either.  Further,  I  was 
lazy  and  I  wanted  full-screen  editing 
ability,  flexible  printing,  and  large  capac¬ 
ity.  In  short,  I  wanted  a  large  system!  In 
fact,  all  I  had  was  a  small  system. 

It  was  then  that  the  Avocet  ad  in 
some  of  the  computer  magazines  caught 


my  eye.  As  a  CP/M  cross  assembler  for 
the  6809,  my  dreams  were  fulfilled.  I 
could  have  all  the  powerful  CP/M  tools  1 
wanted  and  still  be  able  to  put  things 
together  for  a  6809.  I  could  document 
my  code  in  as  much  detail  as  I  wanted.  I 
could  modularize  as  much  as  I  wanted. 
I  could  work  with  6809  code  in  a  con¬ 
venient  way. 

It  wasn’t  long  before  I  started  put¬ 
ting  together  some  6809  software  in¬ 
cluding  some  communications  packages 
and  a  simple  Forth  system.  I  found  out 
just  how  lazy  I  had  become  when  I  tried 
to  go  back  to  the  little  6809  assembler  I 
had.  It  was  good,  but  just  vvasn’t  made 
for  the  kind  of  programming  I  was  doing. 

Avocet  produces  a  whole  line  of 
cross  assemblers  which  include  assemblers 
for  the  following  processors:  6805,  6809, 
RCA1802  (COSMAC),  Intel  MCS-48  & 
UPI-41  families,  Intel  8051,  MOS  6502 
&  650X  family ,  Motorola  6800/680 1  fami¬ 
ly,  NEC  7500  family,  Fairchild  F8,  MOS- 
TEK  F8/3870  family,  National  COP400, 
and  the  Zilog  Z8  family.  Quite  a  list. 

No  assembler  is  worth  its  salt,  though, 
unless  it  can  produce  good  code.  The 
Avocet  6809  assembler  does  as  far  as  I 
have  gone  with  it. 

So  far,  I  haven’t  run  across  any  errors 
not  traceable  to  my  own  programming  er¬ 
rors.  If  the  assembler  would  only  assemble 
what  I  want  instead  of  what  I  type.  But 
the  point  is  that  it  does  do  what  I  type! 

The  basic  assember  syntax  is  roughly 
the  same  as  for  a  standard  8080  assembler 
including  standard  pseudo-ops  such  as 
DW,  DB,  etc.  The  write-up  with  the  sys¬ 
tem  says  that  all  the  assemblers  stay  with 
these  conventions.  I’m  not  sure  I  agree 
that  this  is  the  best  though  I’m  sure  it 
makes  development  and  maintenance 
easier  for  the  Avocet  people. 

Personally,  I  woukl-rather  have  seen 
the  pseudo-ops  closer  to  those  used  by 
the  standard  system  for  the  6809,  but  I 
can  live  with  anything  as  long  as  it  pro¬ 
duces  the  code  I  want. 

The  assembler  produces  code  in  one 
of  two  output  formats,  either  Intel  Hex 
format  or  MIKBUG  format.  I  use  the 
Intel  Hex  format  mostly  out  of  habit. 

This  is  a  nice  assembler  with  reasona¬ 
ble  documentation  for  the  experienced 
programmer.  It  carries  out  the  job  I  want  it 
to  do;  after  all,  isn’t  that  what  it  should 
do? 
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BCPL  —  The  Language  and  Its  Compiler 
by  Martin  Richards 

and  Colin  Whitby-Strevens 
Cambridge  University  Press 
173  pages,  $10.95 
Reviewed  by  George  W.  Jolly 

They  say  you  can’t  tell  a  book  by  its 
cover,  but  sometimes  I’m  not  so  sure.  The 
cover  of  BCPL  is  a  gentle  interplay  of  two 
colors,  blue  and  green,  producing  results 
you  might  think  would  require  three  or 
more  inks.  BCPL  is  a  language  very  much 
in  that  style,  favoring  careful  design  over 
expensive  implementation. 

BCPL  (Basic  CPL)  is  a  systems  pro¬ 
gramming  language  designed  by  Martin 
Richards  in  1967.  The  language,  devel¬ 
oped  mostly  over  the  subsequent  five 
years,  has  been  installed  on  at  least 
twenty- five  different  computer  systems. 
It  has  been  used  for  applications  includ¬ 
ing  operating  systems,  compilers,  editors, 
databases  —  in  other  words,  for  a  broad 
spectrum  of  systems  work. 

In  The  C  Programming  Language, 
Kernighan  and  Ritchie  credit  the  language 
BCPL  for  many  of  C’s  most  important 
ideas.  BCPL  influenced  the  language  B 
written  for  UNIX  by  Ken  Thompson  in 
1970,  and  B  passed  this  influence  on  to 
C.  However,  BCPL  and  C  are  quite  dif¬ 
ferent,  perhaps  most  importantly  in  the 
handling  of  data  types. 

Many  modern  languages  have  a  varie¬ 
ty  of  data  types  built  into  the  compiler. 
Such  types  might  be  integer,  floating 
point,  character,  pointer,  and  so  on. 
BCPL,  on  the  other  hand,  has  only  one 
type,  the  machine  word.  The  compiler 
wastes  no  time  identifying  the  legality  of 
a  construct  for  the  data  items  involved, 
because  all  data  items  are  alike.  In  BCPL, 
address  variables,  or  pointers,  are  easy  to 
use  because  indirect  addressing  is  a 
fundamental  operator.  Any  data  item 
may  contain  an  address. 

One  interesting  result  of  this  inex¬ 
pensive  philosophy  is  that  the  elements 
of  an  array  need  not  all  be  the  same 
“type.”  (Try  having  integers,  characters 
and  pointers  in  the  same  array  in  standard 
FORTRAN!)  Other  languages  do  provide 
this,  but  as  an  extra  feature.  In  BCPL  it  is 
a  consequence  of  the  underlying  design. 
(Funny  how  FORTH  comes  to  mind  at 
this  point.) 

Example  BCPL  routines  illustrate  the 
power  of  the  language.  One  example 
given  is  a  formatted  output  procedure  ac¬ 


cepting  a  format  string  (analogous  to  a 
FORTRAN  format)  as  the  first  argument, 
and  the  data  list  as  subsequent  arguments. 
A  procedure  receives  its  arguments  as  ari 
array  of  addresses.  It  is  a  simple  matter 
to  scan  this  array  with  a  pointer  variable, 
accessing  each  parameter  in  turn.  Another 
pointer  variable  holds  the  address  of  an 
appropriate  editing  procedure  as  indi¬ 
cated  by  the  format  string.  This  is  a  sim¬ 
ple  procedure  with  elegant  results. 

Other  example  programs  include  an 
interactive  debugging  program  and  the 
lexical/syntax  scanner  from  the  BCPL 
compiler.  The  latter  is  discussed  in  de¬ 
tail,  with  a  page  of  program  facing  a  page 
of  explanatory  text.  The  applicative  ex¬ 
pression  tree  produced  by  the  scanner  is 
an  interesting  topic  in  itself. 

Another  interesting  topic  of  this 
book  is  language  portability.  The  authors 
illustrate  a  method  of  bootstrapping  the 
compiler  onto  a  new  system  by  generat¬ 
ing  a  simplified  pseudo-code  on  an  exist¬ 
ing  installation.  They  also  discuss  com¬ 
mon  library  procedures  that  exist  in  most 
BCPL  installations.  These  topics  may  be 
of  interest  to  implementors  of  other  lan¬ 
guages. 

In  summary,  BCPL  is  a  well-written 
book  serving  several  possible  needs.  It  de¬ 
scribes  an  influential  (and  useful)  com¬ 
puter  language,  illustrates  an  elegant  pro¬ 
gramming  philosophy,  and  gives  practical 
examples  of  compiler  techniques.  The 
authors’  straightforward  explanations,  like 
the  cover  design,  complement  the  elegant 
simpilicty  of  BCPL. 


User’s  Guidebook  to  Digital  CMOS 
Integrated  Circuits 
by  Eugene  R.  Hnatek 
McGraw-Hill 
339  pages,  $29.00 
Reviewed  by  Eunice  B.  Stetson 

User’s  Guide  to  Digital  CMOS  In¬ 
tegrated  Circuits  by  Eugene  R.  Hnatek  is 
not  a  book  for  the  uninitiated.  It  is  most 
likely  to  appeal  to  design  engineers  and 
sophisticated  hobbyists.  It  assumes  some 
knowledge  of  semiconductors,  small-  and 
medium-scale  logic  circuits,  conversions 
between  digital  and  analog  signals,  and 
computer  hardware.  Very  little  know¬ 
ledge  of  mathematics  beyond  the  ability 
to  read  complex  graphs  is  assumed.  The 
book  is  very  practical  in  orientation. 


Many  applications,  with  schematics, 
manufacturers’  names,  and  part  numbers, 
are  included. 

The  author  makes  clear  the  electrical 
characteristics  of  CMOS  as  compared 
with  other  IC  logic  families.  He  does  not 
pretend  to  discuss  all  CMOS  integrated 
circuits  but  concentrates  instead  on 
medium-  and  large-scale  IC’s  developed 
since  1977. 

The  author  uses  many  schematics 
and  graphs  and  some  charts  and  timing 
diagrams  to  explain  the  exciting  and 
promising  developments  in  CMOS  and 
SMOS/SOS  (silicon  on  sapphire)  techno¬ 
logy  and  applications  in  telecommuni¬ 
cations,  computers  and  process  control¬ 
lers.  He  envisions  many  new  uses  for 
CMOS  large-scale  integration,  particularly 
in  the  interfacing  of  analog  and  digital  sig¬ 
nals  on  a  single  IC.  Currently,  applica¬ 
tions  of  CMOS  microprocessors  are  con¬ 
centrated  in  the  automotive,  games,  and 
TV  industries  rather  than  in  the  computer 
field. 

The  author  does  an  outstanding  job 
of  making  his  graphs  understandable  with 
labelling  and  notes  on  the  graphs.  Cir¬ 
cuit  diagrams  for  MSI  and  LSI  integrated 
circuits  are  arranged  in  a  logical  sequence 
with  explanation. 

In  discussing  flip-flops,  memory  cells, 
and  shift  registers,  the  author  uses  sche¬ 
matics  with  FET  symbols  rather  than 
logic  symbols.  Later  he  treats  counters, 
timers,  multiplexers,  comparators,  de¬ 
coders,  VARTs,  and  microprocessors  as 
black  boxes.  As  a  teacher  I  would  have 
preferred  a  more  orderly  progression 
from  FETs  to  logic  symbols  to  flip-flops 
to  shift  registers,  multiplexers,  etc.  as  the 
basic  building  blocks  of  which  circuits  are 
composed.  However,  in  that  this  book  is 
intended  as  a  reference  book  and  not  a 
text  book,  this  should  not  be  a  problem. 
As  with  all  books  which  use  manufactur¬ 
ers’  data  and  diagrams,  there  are  differ¬ 
ences  in  symbols  and  conventions  with 
which  the  reader  is  used  to  coping. 

Generally,  the  author’s  explanations 
are  clear,  though  as  with  most  authors 
what  follows  “it  can  be  seen  that  ...”  is 
not  always  obvious.  The  author  clearly 
knows  his  subject  well.  At  times  he  makes 
beautifully  clarifying  statements.  This 
book,  compared  with  others  in  its  field,  is 
clearly  written,  supplemented  with  many 
excellent  pictorials,  and  does  an  authori¬ 
tative  job  in  the  areas  covered. 

(Continued  on  page  72) 
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CP/M  EXCHANGE 


by  Robert  Blum 


Digital  Research  created  a  stir  when 
they  announced  CP/M  Plus  (alias  CP/M 
3)  several  months  ago.  Preliminary  specu¬ 
lation  on  the  system’s  content  ranged 
from  a  simple  maintenance  release  to  full 
concurrent  operation. 

If  you  consider  yourself  a  hacker,  a 
unique  individual  who  treats  inadequacy 
as  an  opportunity,  CP/M  Plus  will  be  bit¬ 
tersweet.  Many  of  its  performance  options 
are  and  have  been  available  in  the  public 
domain  for  years.  If  nothing  else,  CP/M 
Plus  verifies  that  when  hackers  speak,  the 
manufacturers  listen.  It  just  takes  them  a 
little  while  to  react. 

Even  though  I  had  hoped  for  more, 
the  official  release  is  anything  but  disap¬ 
pointing.  It  is  chock-full  of  new  features 
geared  to  performance  and  versatility, 
and  is  a  major  departure  from  the  CP/M 
we  have  grown  to  love  and  respect.  DR 
views  CP/M  Plus  as  a  new  product  and 
it  will  be  maintained  and  marketed 
separately.  At  least  for  now,  it  will  not 
obsolete  CP/M  2.2. 

Over  the  next  few  months  I  will  be 
covering  various  aspects  of  CP/M  Plus: 
does  it  work  as  advertised ;  how  difficult 
is  it  to  implement;  is  it  worth  a  $350  in¬ 
vestment?  Getting  to  know  a  new  product 
cannot  be  effectively  accomplished  alone. 
Share  your  experiences  and  thoughts  with 
the  rest  of  us  by  dropping  me  a  note  or 
calling  me  in  the  evening.  Your  input  will 
be  appreciated  by  one  and  all. 

Before  getting  into  this  month’s  top¬ 
ic,  I  need  some  help.  Is  there  a  patch  for 
CP/M  2.2’s  CCP  that  will  automatically 
search  user  area  0  for  a  .COM  file  that 
was  not  found  in  the  current  user  area?  If 
you  have  one,  please  send  it  along  or 
point  me  to  where  I  can  find  it. 

After  a  long  wait,  CP/M  Plus  is  now 
being  shipped.  By  the  time  this  column  is 
published,  it  will  probably  be  available 
through  mail  order  and  possibly  from  a 
few  manufacturers.  This  estimate  may  be 
a  little  optimistic  because  implementation 
of  all  CP/M  Plus’s  new  features  requires 
considerable  attention  to  both  hardware 
and  software. 

Even  though  I  have  not  received  my 
own  distribution  version  of  CP/M  Plus,  I 
have  been  able  to  gather  up  two  of  the 
three  manuals  and  spend  a  few  hours 
using  it.  What  a  pleasant  surprise!  The 
documentation  has  been  completely  re¬ 
written  and  downsized  to  wedgy  format. 
Each  topic  is  thoroughly  discussed  in 
plain  English,  with  only  minimal  use  of 


buzz  words,  and  is  accompanied  by 
plenty  of  examples. 

Sitting  at  the  keyboard  for  the  first 
time  was  disappointing.  I  had  hoped  for 
concurrent  operation,  or  at  least  a  built-in 
print  spooler.  CP/M  Plus  remains  single 
user  and  still  prompts  with  the  familiar 
A>.  I  soon  learned,  however,  that  all 
other  aspects  of  the  system  are  new,  and 
verified  that  this  is  a  completely  new 
product.  After  only  a  few  minutes  at  the 
keyboard  I  was  comfortable  with  the 
operator  interface  and  swear  by  the  addi¬ 
tional  line-editing  features.  For  those 
who  are  new  to  CP/M,  the  HELP  com¬ 
mand,  which  displays  summarized  infor¬ 
mation  on  all  the  commands,  will  un¬ 
doubtedly  prove  invaluable. 

The  actual  performance  of  the  sys¬ 
tem,  and  which  features  can  be  imple¬ 
mented,  is  predicated  on  how  the  system 
is  generated.  As  a  replacement  for  CP/M 
2.2  in  a  standard  64K  or  less  environment 
(nonbanked),  CP/M  Plus  offers  less  than 
96K  of  banked  memory  when  available. 

Command -line  editing  on  nonbanked 
systems  remains  the  same  as  CP/M  2.2, 
but  is  greatly  improved  on  banked  sys¬ 
tems.  In  the  banked  environment  it  is  no 
longer  necessary  to  retype  a  command  if 
a  mistake  is  made.  Simply  move  the  cur¬ 
sor  to  the  error  and  correct  it  by  inserting 
or  deleting  characters.  Even  after  hitting 
return,  commands  can  be  redisplayed  and 
edited  provided  a  transient  program  was 
not  executed.  Refer  to  Table  1  on  page 
76  for  a  complete  comparison  of  the 
available  editing  functions. 

A  host  of  new  commands  has  been 
added  to  those  that  are  carried  over  from 
older  versions  of  CP/M.  DIRectory, 
ERAse,  REName,  TYPe,  and  USEr  are 
improved  while  DIRSys  has  been  added 
to  display  system  files  which  previously 
required  the  use  of  STAT.  Depending  on 
command-line  options,  transient  pro¬ 
grams  may  be  automatically  loaded  to 
assist  the  built-in  commands  of  the  CCP. 
I  have  summarized  the  built-in  commands 
in  Table  2  (page  76).  The  descriptions 
used  for  each  command  are  excerpts  from 
DR’s  manuals.  I  do  this  so  that  you  can 
sample  the  flavor  of  the  new  documen¬ 
tation. 

Enhanced  command  editing  is  only  a 
part  of  the  beauty  of  CP/M  Plus.  Many 
new  utilities  have  been  added  and  those 
that  were  retained  from  older  versions  are 
now  more  useful.  Also  included  is  the 
entire  RMAC  program  development  pack¬ 
age  which  previously  cost  $200.  Refer  to 


Table  3  (page  78)  for  a  summary  of  the 
utility  programs. 

Before  generating  the  system,  you 
are  faced  with  a  dilemma.  The  minimum 
system  configuration  has  been  increased 
to  32K  and  CP/M  Plus  requires  8.5K.  By 
the  time  you  add  in  the  size  of  your  BIOS 
a  great  deal  of  memory  has  been  taken 
up,  even  when  a  full  64K  is  available.  To 
make  full  use  of  the  system  requires  at 
least  96K  of  bank -select  memory.  Through 
the  use  of  this  additional  memory,  it  is 
entirely  possible  to  have  a  62K  TPA  be¬ 
cause  only  a  minimum  BIOS  and  BDOS 
are  resident  in  the  application  bank.  The 
real  controlling  logic  is  placed  in  the 
other  bank  along  with  directory  hash 
tables  and  sector  buffers.  Because  of  this, 
I  would  anticipate  the  introduction  of 
more  8 -bit  machines  with  25 6K  of  mem¬ 
ory  in  the  not-too-distant  future. 

Disk  space  reserved  for  the  system 
tracks  has  been  reduced  by  placing  the 
operating  system  components  into  regular 
disk  files.  This  will  be  especially  impor¬ 
tant  for  those  systems  that  require  very 
large  BIOSs.  When  booting  the  system,  a 
small  loader  from  the  system  tracks  is 
read  into  memory,  which  then  completes 
the  loading  process.  In  light  of  more  com¬ 
mon  use  of  hard  disks,  individual  file  size 
has  been  increased  to  33  megabytes  and 
disk  capacities  of  512  megabytes  are 
possible. 

Generation  of  the  system  is  handled 
by  a  transient  program  called  GENCPM 
which  combines  the  various  system  com¬ 
ponents  with  your  BIOS.  The  generation 
process  is  remarkably  similar  to  that  used 
with  MP/M,  as  are  most  other  features  of 
CP/M  Plus. 

CP/M  Plus  is  not  for  everyone.  Its 
initial  cost  is  high  and  it  requires  expanded 
hardware  resources  if  it  is  to  be  used  to 
its  fullest  extent.  But  the  costs  associated 
with  its  implementation  will  not  seem 
nearly  as  high  if  you  need  all  the  develop¬ 
ment  tools  which  are  included.  Function¬ 
alism  is  the  keyword  to  describing  this 
new  offering  from  Digital  Research. 

Next  month  I  will  continue  with  the 
internals  of  CP/M  Plus  and  any  experi¬ 
ences  that  I  hear  from  you.  You  can  reach 
me  by  phone  at  (404)  449-8948. 

(Tables  I  and  II  on  page  76) 
(Table  III  on  page  78) 
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TABLE  III 
Utilities 


COPYSYS  The  COPYSYS  command  copies  the  CP/M  3 
system  from  a  CP/M  3  system  disk  to  another  disk  with 
the  same  format  as  the  original  system  disk.  For  example, 
if  the  system  disk  is  single  density,  the  disk  you  copy  on¬ 
to  must  also  be  in  single -density  format. 

DATE  The  DATE  command  is  a  transient  utility  that 
lets  you  display  and  set  the  date  and  time  of  day.  When 
you  start  CP/M  3,  the  date  and  time  are  set  to  the  crea¬ 
tion  date  of  your  CP/M  3  system.  Use  DATE  to  change 
this  initial  value  to  the  current  date  and  time. 

DEVICE  The  DEVICE  command  is  a  transient  utility 
that  displays  current  assignments  of  logical  devices  and 
the  names  of  physical  devices.  This  command  also  sets 
the  communications  protocol  and  speed  of  a  peripheral 
device. 

DUMP  DUMP  displays  the  contents  of  a  file  in  hexa¬ 
decimal  and  ASCII  format. 

ED  The  ED  utility  is  a  line-oriented  context  editor. 

This  means  that  you  create  and  change  character  files 
line-by-line,  or  by  referencing  individual  characters 
within  a  line. 

GENCOM  The  GENCOM  command  is  a  transient  utility 
that  creates  a  special  COM  file  with  attached  RSX  files. 
RSX  files  are  used  as  Resident  System  extensions. 
GENCOM  places  a  special  header  at  the  beginning  of  the 
output  program  file  to  indicate  to  the  system  that  RSX 
loading  is  required.  It  can  also  set  a  flag  to  keep  the  pro¬ 
gram  loader  active. 

GET  The  GET  command  is  a  transient  utility  that 

directs  CP/M  3  to  take  console  input  from  a  file.  The  file 
can  contain  CP/M  3  system  commands  and/or  input  for 
a  user  program.  If  you  use  the  SYSTEM  option,  GET  im¬ 
mediately  takes  the  next  system  command  from  the  file. 

HELP  The  HELP  command  is  a  transient  utility  that 
provides  information  for  all  of  the  CP/M  3  commands 
described  in  the  manual.  In  the  distributed  CP/M  3  sys¬ 
tem,  HELP  presents  general  information  on  a  command 
as  a  topic,  and  detailed  information  as  a  subtopic.  HELP 
with  no  command  tail  displays  a  list  of  all  the  available 
topics.  HELP  with  a  topic  in  the  command  tail  displays 
information  about  that  topic,  followed  by  any  available 
subtopics.  HELP  with  a  topic  and  a  subtopic  displays 
information  about  the  specific  subtopic. 

HEXCOM  The  HEXCOM  command  is  a  transient  utility 
that  generates  a  command  file  (filetype  COM)  from  a 
hex  input  file.  It  names  the  output  file  with  the  same 
filename  as  the  input  file  but  with  filetype  COM. 
HEXCOM  always  looks  for  a  file  with  filetype  HEX. 

INITDIR  The  INITDIR  command  can  initialize  a  disk 
directory  to  allow  date  and  time  stamping  of  files  on 
that  disk  or  remove  date  and  time  stamps. 

LIB  The  LIB  command  is  used  to  create  and  main¬ 

tain  a  library  of  relocatable  object  modules.  Use  the  LIB 
utility  to  create  libraries  and  to  append,  replace,  select, 
or  delete  modules  from  an  existing  library.  You  can  also 
use  LIB  to  obtain  information  about  the  contents  of 
library  files. 

LINK  The  LINK  command  combines  relocatable 
object  modules  such  as  those  produced  from  RMAC  into 


a  .COM  file  ready  for  execution.  Relocatable  files  can 
contain  external  references  and  publics.  Relocatable  files 
can  reference  modules  in  library  files.  LINK  searches  the 
library  files  and  includes  the  referenced  modules  in  the 
output  file. 

MAC  The  MAC  utility  assembles  .ASM  disk  files  into 
.HEX  object  files.  It  also  has  the  ability  to  process 
macros. 

PATCH  The  PATCH  command  displays  or  installs  patch 
N  to  the  CP/M  3  system  or  command  files. 

PIP  PIP  is  a  transient  utility  that  copies  one  or  more 

files  from  one  disk  and/or  user  number  to  another.  PIP 
can  rename  a  file  after  copying  it;  combine  two  or  more 
files  into  one  file;  and  copy  a  character  file  from  one 
disk  to  the  printer  or  other  auxiliary  logical  output 
device.  PIP  can  create  a  file  on  disk  of  input  from  the 
console  or  other  logical  input  device.  PIP  can  also  transfer 
data  from  a  logical  input  device  to  a  logical  output  de¬ 
vice,  thus  the  name  Peripheral  Interchange  Program. 

PUT  The  PUT  command  is  a  transient  utility  that 

lets  you  direct  console  output  or  printer  output  to  a  file. 
PUT  allows  you  to  direct  the  system  to  put  console  out¬ 
put  or  printer  output  to  a  file  for  the  next  system  com¬ 
mand  or  user  program  entered  at  the  console.  Or  PUT 
directs  all  subsequent  console  or  printer  output  to  a  file 
when  you  include  the  SYSTEM  option. 

RMAC  The  RMAC  utility  is  operationally  comparable 
to  MAC  except  its  output  is  in  .REL  form. 

SAVE  The  SAVE  command  copies  the  contents  of 
memory  to  a  disk  file.  To  use  the  SAVE  utility,  first 
issue  the  SAVE  command,  then  run  your  program  which 
reads  a  file  into  memory.  When  your  program  exits,  it 
exits  to  the  SAVE  utility.  The  SAVE  utility  prompts  you 
for  the  filespec  to  which  the  memory  is  to  be  copied, 
and  the  beginning  and  ending  address  of  the  memory  to 
be  saved. 

SET  The  SET  command  initiates  password  protection 

and  time  stamping  of  files  in  the  CP/M  3  system.  It  also 
sets  file  and  device  attributes,  such  as  the  Read-Only, 
SYS,  and  user-definable  attributes.  It  lets  you  label  a 
disk  and  password -protect  the  label. 

SETDEF  The  SETDEF  command  lets  you  display  or 
define  the  disk  search  order,  the  temporary  drive,  and 
the  filetype  search  order. 

SHOW  The  SHOW  utility  displays  the  disk  drive 
attributes. 

SID  The  SID  utility  replaces  the  DDT  program.  It 

offers  more  commands  and  flexibility. 

SUBMIT  The  SUBMIT  command  lets  you  execute  a 
group  or  batch  of  commands  from  a  SUB  file,  which  is 
a  file  with  filetype  of  SUB. 

TYPE  The  TYPE  utility  displays  the  contents  of  an 
ASCII  disk  file  on  your  screen.  A  paging  option  is  now 
available. 

XREF  The  XREF  utility  provides  a  cross-reference 
summary  of  variable  usage  in  an  assembler  program. 
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16-BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


MS-DOS  vs.  CP/M-86 

Jim  Howell  of  San  Jose,  California, 
has  written  me  a  couple  of  interesting  let¬ 
ters  regarding  my  coverage  of  the  two 
major  operating  systems  for  the  8086/88 
microcomputer  family.  I  have  taken  the 
liberty  of  editing  some  of  his  comments 
and  my  replies  into  the  form  of  a  dialogue 
for  this  column,  and  hope  he  will  forgive 
me  for  the  slight  rearrangements  and 
changes  of  wording  that  were  necessary. 

JH:  In  the  December  issue  of  DDJ,  you 
say  that  the  reason  for  “excessive”  cover¬ 
age  of  the  8086/88  is  a  table  that  indicates 
more  8086/88s  in  use  than  other  16-bit 
processors.  First,  the  numbers  in  that 
table  do  not  necessarily  indicate  the  level 
of  interest  in  the  various  processors.  For 
example,  I  am  sure  there  are  many,  in¬ 
cluding  myself,  who  do  not  have  a  68000- 
based  computer,  but  are  nevertheless 
interested  in  that  processor.  In  any  case, 
if  you  are  going  to  use  the  numbers  in 
that  table  to  justify  the  contents  of  your 
column,  you  should  be  devoting  78%  of 
your  column  to  the  8086/88,  15%  to  the 
68000,  and  7%  to  the  Z8000.  (What  about 
the  TI-9900  and  National’s  16000?). 

Second,  if  you  are  going  to  devote 
100%  of  your  column  to  the  8086/88 
(which  is  the  case  so  far),  perhaps  the  col¬ 
umn  should  be  called  “8086/88  Toolbox” 
or  even  “IBM  PC  Toolbox.”  The  title  “16- 
Bit  Software  Toolbox”  promises  broader 
coverage  than  just  a  single  processor. 
Actually,  I  suspect  that  the  real  reason 
for  covering  only  the  8086/88  is  that  you 
own  (or  have  a  lot  of  access  to)  an  IBM 
PC  and  have  little  or  no  access  to  systems 
that  use  other  16 -bit  processors. 

RD:  You  certainly  have  penetrated  right 
to  the  heart  of  the  matter,  since  it  is  true 
that  untO  very  recently  I  didn’t  have  any 
access  to  a  68000  system.  But  again,  this 
is  relevant  to  the  content  of  the  column 
and  is  not  a  coincidence.  The  long-range 
objective  of  the  “16-Bit  Software  Tool¬ 
box”  is  to  provide  useful  subroutines  and 
utilities  for  the  most  commonly  used  16- 
bit  microprocessors.  Although  Motorola’s 
68000  architecture  and  instruction  set 
are  elegant,  their  decision  to  make  a  total 
break  with  the  architecture  of  their  8 -bit 
microprocessor  family  has  caused  a  tre¬ 
mendous  lag  in  the  appearance  of  afforda¬ 
ble  operating  systems  and  software  devel¬ 
opment  tools  for  68000-based  personal 
computers. 

I  do  plan  to  provide  increasing  cover¬ 
age  of  the  68000  in  the  coming  months, 


and  now  have  both  a  Cromemco  Dual 
Z80/68000  CPU  and  a  Godbout  68000 
CPU  to  work  with.  But  I’m  still  waiting 
for  my  copy  of  CP/M-68K,  which  was 
announced  and  demonstrated  at  the 
CP/M-83  show  in  January  but  is  still 
not  being  shipped  to  customers. 

JH:  I  have  noticed  that  your  recent  col¬ 
umns  have  criticized  various  aspects  of 
MS-DOS  (apparently  you  are  “pushing” 
CP/M-86,  for  some  reason).  We  have 
used  an  IBM  PC  at  work  for  the  past 
several  months,  using  only  PC- DOS,  and 
have  had  no  problems  with  it. 

RD:  I  do  not  have  any  vested  interest  in 
either  CP/M-86  or  MS-DOS,  and  am  not 
trying  to  “push”  one  operating  system  in 
preference  to  another.  Since  MS-DOS 
presently  dominates  the  8086/88  user 
base,  I  do  feel  that  its  problems  (and 
ways  of  dealing  with  them)  should  re¬ 
ceive  more  space  in  the  column.  It  is  true 
that  I  feel  the  Digital  Research  family  of 
operating  systems  and  language  compilers 
is  much  more  “robust”  than  the  Micro¬ 
soft  products;  this  is  only  an  opinion, 
but  it  is  based  on  many  published  com¬ 
parisons  and  compiler  benchmarks,  and 
on  my  own  extensive  experience  imple¬ 
menting  systems  tools  on  CP/M,  CP/M-86, 
and  MS-DOS. 

JH:  Benchmarks  published  in  the  No¬ 
vember  1982  column  showed  PC -DOS 
outperforming  CP/M-86  on  two  out  of 
three  disk-intensive  tests.  This  was  fol¬ 
lowed  immediately  by  several  paragraphs 
entitled  “And  Now  the  Bad  News”  about 
how  changing  disks  in  the  middle  of  an 
operation  under  PC-DOS  could  clobber 
data  on  a  disk,  but  with  CP/M-86  all  you 
get  is  a  harmless  little  error  message.  You 
neglected  to  state  that  any  editing  you 
may  have  done  to  the  file  under  CP/M-86 
is  lost.  Perhaps  that  seemed  too  obvious 
to  mention,  but  it  would  have  balanced 
the  presentation  a  little. 

In  January  1983,  a  letter  from  a 
reader  appeared  on  the  above  subject  and 
on  how  to  recover  most  of  the  data  on  the 
damaged  disk.  This  section  had  the  rather 
negative  title:  “Coping  with  PC-DOS.” 
The  most  eye-catching  line  in  Isaac  Davi- 
dian’s  letter  was:  “Unfortunately,  I  had 
no  backup.  .  .  .”  If  this  reader  had  had  a 
backup,  he  would  have  had  much  less  of  a 
problem.  I  have  not  used  CP/M-86,  but  I 
used  CP/M-80  at  a  previous  job  and 
found  its  READ-ONLY  DISK  error 
rather  annoying.  I  always  wondered  why 
the  system  couldn’t  automatically  do 


whatever  was  required  to  make  the  disk 
not  read-only,  instead  of  making  the  user 
start  over.  CP/M-86  apparently  handles 
new  disks  as  READ-ONLY  also. 

RD:  Mr.  Howell  correctly  points  out 

that,  if  you  switch  disks  at  an  inappro¬ 
priate  time  under  CP/M-86,  you  will  lose 
the  contents  of  the  file  you  are  currently 
working  on.  However,  this  is  all  you  will 
lose.  The  integrity  of  the  other  files  on 
both  the  new  and  previous  disks  is  care¬ 
fully  protected  by  the  operating  system. 
The  inexcusable  part  of  PC -DOS’s  han¬ 
dling  of  new  disks  is  not  that  you  can  lose 
your  currently  accessed  file,  but  you  can 
lose  all  of  the  files  on  the  new  disk;  and  the 
directory  is  trashed  in  such  a  manner  that 
it  is  nearly  impossible  to  reconstruct  it. 

This  is  in  direct  contradiction  to  the 
PC-DOS  manual,  page  D-12,  under  Func¬ 
tion  10H  Close  File,  which  states:  “This 
function  must  be  called  after  file  writes 
to  insure  [sic]  all  directory  information 
is  updated.  On  entry,  DS:DX  point  to 
an  opened  FCB.  The  disk  directory  is 
searched  and  if  the  file  is  found,  its  posi¬ 
tion  is  compared  with  that  kept  in  the 
FCB.  If  the  file  is  not  found  in  its  correct 
position  in  the  directory,  it  is  assumed 
the  diskette  was  changed  and  [register] 
AL  returns  X’FF’.  Otherwise,  the  direc¬ 
tory  is  updated  to  reflect  the  status  in  the 
FCB  and  AL  returns  00.”  If  PC-DOS  really 
handled  file  closure  the  way  the  manual 
states,  everything  would  be  peachy. 

As  for  Mr.  Davidian’s  lack  of  backups, 
we  are  all  human  and  I  am  sure  we  have  all 
failed  at  one  time  or  another  to  make  back¬ 
up  disks  as  often  as  would  be  desirable. 
The  operating  system  ought  to  help  pro¬ 
tect  us  from  our  frailties,  not  exploit  them ! 

JH:  My  own  feelings  on  CP/M-86  vs. 
PC-DOS  are  based  on  Dave  Cortesi’s  col¬ 
umn  of  several  months  ago,  on  my  four 
years  of  working  with  CP/M-80,  and  on 
six  months  of  working  with  PC-DOS. 
CP/M-86  is,  as  I  understand,  not  much 
more  than  a  direct  copy  of  CP/M-80.  PC- 
DOS  is  based  on  CP/M-80,  but  not  as 
heavily  as  CP/M-86.  Microsoft  and  pre¬ 
vious  authors  attempted,  with  PC-DOS, 
to  make  some  improvements  in  moving  to 
the  8086/88,  such  as: 

•  Time  and  date  stamping  of  disk  files. 

•  Changing  the  name  PIP  to  COPY  and 
making  it  a  built-in  command. 

•  Putting  the  parameters  of  COPY  and 
RENAME  in  the  “right”  order. 

•  Allowing  disk  read  and  write  in  blocks 
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[record  sizes]  of  anything  the  user 
wishes,  not  just  128  bytes  as  with 
CP/M.  There  is  still  much  room  for 
improvement  here,  but  it  sometimes 
will  allow  reading  or  writing  a  file 
with  one  call  to  the  system  (not 
counting  open  and  close),  instead  of 
having  to  write  128  bytes  at  a  time 
in  some  sort  of  a  loop. 

•  Showing  the  exact  size  of  the  file  in 
the  directory  listing. 

•  The  ability  to  use  device  names,  such 
as  CON:  and  LPT1:  as  the  “filename” 
in  an  FCB,  which  gives  some  degree 
of  device  independence.  Again,  there 
is  room  for  more  improvement  here, 
since  real  device  independence  is 
what  one  would  really  like. 

•  The  batch  facility  of  PC- DOS  is 
much  better  than  CP/M’s  SUBMIT, 
which  is  a  real  kludge.  For  example, 
the  AUTOEXEC  facility  of  PC-DOS 
allows  executing  a  program  or  series 
of  programs  on  power  up.  We  use 
this  at  work  to  read  the  date  and  time 
from  a  battery-powered  clock  to  set 
the  system’s  date  and  time.  Doing 
this  under  CP/M-86  requires,  as  far 
as  I  know,  modifying  CP/ M’s  boot 
file  (or  giving  the  appropriate  com¬ 
mand  manually  each  time  the  system 
is  booted). 

RD:  Points  granted,  with  the  following 
reservations:  Concurrent  CP/M  and  the 
new  CP/M  Plus  support  time  and  date 
stamping  of  files,  and  additionally  offer 
the  convenience  of  password  protection 
and  “user  areas.”  The  new  CP/Ms  also 
allow  file  access  in  “burst  mode”  where 
up  to  sixteen  128-byte  records  can  be 
transferred  with  a  single  operating  system 
call,  but  this  is  still  much  weaker  than  the 
PC-DOS  block  read/write  functions 
where  the  record  size  can  be  from  1  to 
65,535  bytes.  Concurrent  CP/M  has  the 
capability  to  execute  a  user-supplied 
batch  file  at  cold  start. 

Whether  or  not  PC-DOS’sCOPY  and 
RENAME  parameters  are  in  the  “right” 
order  is  arguable.  CP/ M’s  format  (which 
mimics  an  assignment  statement)  cer¬ 
tainly  seems  natural  to  programmers,  but 
PC-DOS’s  conventions  are  easier  for  new 
computer  users  to  remember. 

In  general,  I  think  we  will  all  benefit 
from  the  intense  rivalry  between  MS- 
DOS  (and  its  clones)  and  CP/M-86.  Both 
systems  already  show  significant  improve¬ 
ments  over  their  8 -bit  counterparts, 
and  the  competition  for  market  share  is 
bound  to  bring  us  many  additional  en¬ 
hancements  in  future  versions.  MS-DOS 
2.0,  which  is  scheduled  for  release  soon, 
incorporates  some  sophisticated  new 
features  including  the  ability  to  load  user- 
designed  peripheral  device  drivers  without 
patching  the  operating  system. 
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IBM  PC  Character  Set  Linker 

Patrick  Banchy,  of  New  York  City, 
wrote  in  with  several  suggested  modifica¬ 
tions  to  the  CLINK  utility  that  was  pub¬ 
lished  in  an  earlier  column. 

In  order  to  get  the  program  to  work 
at  all,  when  assembled  with  the  Microsoft 
Assembler  to  form  an  EXE  file,  several 
pseudo-commands  to  define  segment 
start/ends  must  be  inserted.  Additionally, 
the  instruction: 

MOV  14  [BX]  ,1024 
must  be  modified  to: 

MOV  WORD  PTR  14  [BX]  ,1024 
(the  Microsoft  Assembler  does  not  check 
the  magnitude  of  the  immediate  data  to 
determine  whether  a  16-bit  transfer  is 
necessary).  On  his  system,  instructions 
also  had  to  be  added  to  intialize  byte  32 
of  the  file  control  block  to  zero  before 
the  file  access,  although  on  my  PC  this 
happens  automatically  when  the  program 
is  loaded. 

Patrick  then  made  some  improve¬ 
ments  which  can  be  summarized  as 
follows: 

All  segment  registers  of  a  COM  pro¬ 
gram  are  set  to  the  start  of  the  Program 
Segment  Prefix  (PSP),  so  the  first  three 
instructions  of  CLINK  as  listed  in  DDJ 
are  unnecessary. 

DOS  function  #37  can  be  used  to 
set  the  interrupt  vector  address. 

To  decrease  the  amount  of  memory 
made  unavailable  for  use  by  other  pro¬ 
grams,  he  put  the  code  that  reads  in  the 
file  after  an  ORG  480H  statement,  and 
used  the  default  disk  transfer  address 
(80H).  This  results  in  a  bigger  load  module, 
but  smaller  memory  loss  (1152  bytes  for 
my  version  vs.  1424  bytes  for  Patrick’s). 

Finally,  he  noted  that  if  CLINK  is 
invoked  multiple  times,  it  will  reserve  a 
new  block  of  memory  each  time.  This 
could  become  quite  wasteful,  so  he 
changed  CLINK  to  check  the  contents  of 
the  vector  location  at  007CH.  If  the  link 
is  zero,  CLINK  reads  the  character  (INT 
27H);  if  the  link  is  nonzero,  CLINK  points 
the  disk  transfer  address  to  the  previously 
loaded  table  area,  reads  the  new  table, 
and  then  makes  a  “normal”  exit  (DOS 
function  0). 

FLIP  Utility  for  the  IBM  PC 

Simson  L.  Garfinkel  sent  in  a  pro¬ 
gram  listing  with  the  following  comments: 

“I  own  an  IBM  PC  with  both  the 
color/graphics  and  monochrome  adapters 
installed.  IBM  makes  no  effort  to  support 
users  who  have  both  of  these  interfaces 
installed,  other  than  a  brief  note  on  page 
1-8  of  the  BASIC  manual  on  how  to 
switch  from  one  display  to  another. 

“I  have  written  a  small  program 
(see  listing  on  opposite  page)  which  flips 
from  one  display  to  the  other.  The  pro¬ 
gram  is  designed  to  be  converted  into  a 
COM  file  with  EXE2BIN  program,  and 


for  this  reason  has  no  stack  segment  (this 
generates  an  error  when  linked  which 
should  be  ignored). 

“When  FLIP.COM  is  executed,  if  the 
monochrome  display  was  being  used,  the 
color  screen  is  cleared  and  becomes  the 
system  display,  and  conversely.” 

Users  who  have  a  high-resolution 
color  monitor  will  probably  want  to  alter 
the  program  slightly  so  that  it  selects  the 
80x25  BW  text  mode  when  selecting  the 
graphics  interface. 
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OF  INTEREST 


by  Michael  Wiesenberg 


Mice  Are  Cheaper 
by  the  Thousands 

Lisa  has  a  mouse.  Xerox  has  been 
using  mice  for  years,  particularly  with 
SmallTalk.  Do  you  need  a  mouse?  The 
3G  Micromouse  has  two  pushbuttons 
and  rolls  on  a  table  top,  moving  the 
cursor  on  your  screen  correspondingly. 
You’ll  have  to  do  the  software  inter¬ 
face,  but  3G  will  sell  you  the  hardware 
for  $180,  or  $72  each  in  lots  of  over 
1000.  Reader  Service  No.  101. 


16  Bits  for  Less 

The  Sage  II  68 000 -based  micro¬ 
computer  with  128K  RAM,  running  at 
8MHz  and  2MIPS  (million  instructions 
per  second),  with  one  640  K  floppy, 
and  p-System  OS  costs  less  than 
$3600.  It’s  a  small  3.9-  by  12.5-  by 
16.7-inch  box  to  which  you’ll  need  to 
add  a  terminal.  Expansion  RAM, 
claims  Sage,  is  at  the  industry’s  lowest 
available  price,  $250  per  128K,  and 
you  can  fit  another,  optional  floppy 
into  the  box.  CP/M-68K  is  another 
available  option.  Reader  Service  No. 
103. 

Dynalogic’s  Hyperion  is  a  truly 
portable,  self-contained  16-bit  com¬ 
puter  that  is  compatible  with  the  IBM 
PC  mnning  MS-DOS,  and  costs  under 
$3400.  The  “entry-level”  18-pound 
Hyperion  has  256K  RAM,  one  320K 
554-inch  drive  (that  reads  both  single- 
and  double-density  IBM  PC  diskettes), 
MS-DOS,  Microsoft  Advanced  Disk 
BASIC  with  graphics,  a  7-inch  non¬ 
glare  amber  phosphor  screen  of  80 
columns  by  25  lines  and  five  pages  of 
display  memory,  256  display  charac¬ 
ters,  bidirectional  scrolling,  soft -key 
labels  on  the  25th  display  line,  serial 
and  parallel  ports,  and  a  low-profile, 
detachable  keyboard  with  84  keys,  in¬ 
cluding  ten  function  keys  and  numeric 
keypad  and  optional  audible  key  click. 
Options  include  a  second  floppy  drive 
for  $650;  a  300-baud,  built-in,  direct- 
connect  Bell  103J  compatible  modem 
with  autoanswer  and  autodial  for 
$495;  Dynalogic’s  IN: SCRIBE  text 
editor  for  $175;  Microsoft’s  Multiplan 
spreadsheet  for  $257;  and  a  soft  vinyl 
travelling  case  with  accessory  pockets 
for  $90.  These  options  are  standard  in 
the  $4995  Hyperion  Plus,  which  also 
includes  a  time  and  date  clock  with 


battery  backup  that  keeps  the  time 
even  when  AC  power  is  removed.  You 
can  also  get  Microsoft’s  BASIC  compi¬ 
ler,  COBOL,  Fortran,  and  Pascal. 
Reader  Service  No.  105. 


What  Looks  Like  an  Apple? 

(But  Costs  Less) 

Microcomputer  II  from  HSC  Com¬ 
puter  Services  is  an  Apple-clone  for 
$499  (plus  $15  p&h)  that  runs  Apple- 
Soft  (and  Franklin  Ace)  software  and 
comes  with  64K  RAM,  6502  CPU,  built- 
in  RF  modulator,  high-res  graphics, 
cassette,  printer,  and  cartridge  inter¬ 
faces,  AppleSoft-compatible  BASIC, 
self-diagnosis  cassette,  manuals,  real 
keyboard,  and  switching  power  supply. 
Options  include  printer,  joystick,  12- 
inch  green-phosphor  monitor,  speech 
synthesizer,  Pascal,  Forth,  and  assembly 
language  cartridges,  inventory  control 
and  accounting  cartridges,  RS-232C 
interface,  floppy  disk  drive,  and  disk 
controller.  Reader  Service  No.  107. 


Phone-y  Modem 

Datamate  103  from  Cermetek  Mi¬ 
croelectronics  is  an  intelligent,  300- 
baud,  autodial,  full-duplex  modem 
that  comes  with  slim -line  telephone 
receiver,  for  voice  and  data  communi¬ 
cations.  It  attaches  to  your  computer’s 
RS-232C  port,  stores  the  last  data 
number  and  six  other  numbers  in  its 
nonvolatile  memory,  makes  voice 
calls  even  when  the  modem  is  turned 
off,  dials  from  memory,  and  dials 
until  answered.  The  package  is  $295, 
or  modem  phone  alone  for  $29.95  and 
Datamate  103  for  $269.  They’ve  also 
got  the  same  package  in  Bell-21 2A- 
compatible,  1200 -baud  model.  Reader 
Service  No.  111. 


IBM  Talks  to  Phone 

I’ve  mentioned  PConnection,  from 
Microperipheral,  before:  a  plug-in  IBM 
PC  modem  card  —  direct  connect,  Bell 
103/113  compatible,  with  autodial 
(Touch  Tone  or  pulse)  —  that  answers 
automatically  in  both  originate  and 
answer  modes,  and  fits  inside  the  PC 


IBM  Gone 

Vitek  will  be  distributing  Corona 
Data  Systems’  new  IBM- compatible 
desktop  and  portable  personal  com¬ 
puters,  that  sell  for  about  a  third  less 
than  the  “real  thing.”  You  get  a  green- 
phosphor  monitor  with  640-by-325 


high-resolution  graphics,  disk  drive, 
four  card  slots  (3  54  in  the  portable 
model),  128K  RAM  (expandable  to 
512),  serial  and  parallel  ports,  and 
detachable  keyboard.  Reader  Service 
No.  109. 
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Beat  the  Computer 

Arisoft’s  Mike  Caro’s  Video  Poker 

for  Apple  II  includes  two  games,  Jack¬ 
pot  Video  Poker  and  Poker  Flurry. 
The  former  simulates  the  progressive 
jackpot-type  video  poker  slot  machines. 
Although  the  game  is  functionally 
identical  to  the  Las  Vegas  variety,  it 
contains  several  added  features.  Any 
hand  can  be  replayed.  You  can  set  the 
jackpot  to  what  you  like,  carry  the 
jackpot  over  from  one  playing  session 
to  the  next,  and  ask  the  computer  for 
a  mathematical  analysis  of  how  you’re 
doing.  You  can  get  an  instant  replay  of 
the  last  hand.  Arisoft  describes  the  fea¬ 
ture  this  way:  “Although  this  won’t 
alter  your  results  or  allow  you  to 
change  your  draw,  it’s  good  for  settling 
arguments  about  whether  you  threw 
away  a  pair  by  accident.  It  also  lets 
you  relive  moments  of  glory.”  You  can 
change  the  speed  with  which  the  cards 
are  dealt,  from  superfast  to  slow  mo¬ 
tion.  The  game  is  accompanied  by 
sound  effects,  including  a  victory  song 
when  you  catch  a  big  hand. 

Poker  Flurry  is  a  competitive 
form  of  video  poker.  You  can  play 
against  the  computer,  or  against  a 
friend.  Or  you  can  even  watch  the 


computer  battle  against  itself!  If  you 
do  this,  you  can  also  learn  proper 
strategy  for  these  casino  games  that 
knowledgeable  players  can  get  an  edge 
on.  (This  game  is  the  ultimate  decision 
maker.  For  example,  if  you  don’t 
know  whether  to  go  to  work  today  or 
play  golf,  you  have  the  computer  bat¬ 
tle  itself  under  the  names  *WORK  and 
*GOLF,  and  see  who  wins.)  There’s 
even  a  doubling  facility.  The  disk  costs 
$39.95.  Reader  Service  No.  121. 


Develop  Z8000  on  Z80 

2500  A.D.  Software  has  a  Z8000 
Cross  Development  system  that  runs 
on  any  64K  Z80  CP/M  system.  You 
get  a  Z80  to  Z8000  translator,  8080  to 
Z8000  translator,  and  Z8000  relocat¬ 
ing  macro- cross  assembler.  The  latter 
has  nested  and  recursive  macros,  in¬ 
clude  files,  a  linker  that  links  up  to 
400  files,  and  relocatable  code  genera¬ 
tion.  All  this  and  a  150-page  manual 
for  $179.50.  Reader  Service  No.  123. 


cabinet.  It  used  to  cost  $350.  Now 
they’ve  added  automatic  disconnect 
circuitry  for  failure  or  carrier  loss,  and 
cut  the  price  to  $279.  They’ve  also 
added  to  their  line  an  enhanced  ver¬ 
sion  with  real-time  clock  for  auto¬ 
answer  and  autodial  at  preset  times, 
and  an  additional  serial  I/O  port  to 
increase  the  PC’s  communications 
capabilities,  for  $350.  Reader  Service 
No.  113. 


Zenith  Talks  to  IBM 

Zenith’s  3270  Terminal  Emulation 

package  for  Z-89  and  Z-90  desktop 
computers  includes  software  and  bi¬ 
synchronous  interface  card  for  $750, 
or  software  alone  for  $650.  With  a 
printer,  the  program  emulates  the  IBM 
3276  Model  2  with  3278  printer.  Ze¬ 
nith’s  function  keys  are  used  in  the 
same  way  as  those  of  the  3270  series, 
with  color-coded  labels  included  to 
adapt  keyboards  to  those  of  the  3270. 
You  need  a  modem  with  synchronous 
RS-232C  interface  and  64K  RAM. 
Reader  Service  No.  115. 


Apple  and  IBM 

Are  Now  Speaking  to  Each  Other 

Direct  Connect  from  Trax  trans¬ 
fers  files  between  Apple  II  and  IBM  PC, 
requiring  no  extra  hardware  (beyond  a 
cable  that  they  supply).  This  software 
product  uses  the  PC’s  cassette  port  and 
the  Apple’s  I/O,  with  transfer  rates  of 
10K  bps  and  automatic  error  checking. 
A  “remote  commander”  feature  con¬ 
trols  both  machines  from  the  PC,  using 
only  one  display,  and  permitting  run¬ 
ning  of  Apple  programs  with  standard 
keyboard  input  and  display  on  the  PC. 
You  also  get  a  Pascal  interface  for  your 
$170.  Reader  Service  No.  117. 


Fortran  400  Times  Faster 

Do  you  have  a  CompuPro  8085/88 
with  Hudson  and  Associates’  8087 
Support  Board?  If  so,  you  can  relink 
your  8 -bit  software,  including  Fortran- 
80,  COBOL-80,  BASCOM-80,  and 
MACRO-80,  with  F87LIB.REL,  part 
of  Avant- Code’s  Fortran-87,  and  run 
programs  up  to  400  times  faster  by 
taking  advantage  of  the  8087’s  80-bit 
floating-point  routines.  $200  gets  you 
an  8 -inch  CP/M  disk  and  manual,  and, 
if  you  don’t  have  the  Hudson  board 
(including  5 MHz  8087-3)  —  installation 
of  which  does  not  void  CompuPro’s 
CPU  warranty  —  you  can  get  software 
and  board  for  $695.  Reader  Service 
No.  119. 


Print  Your  Own  Calendars 

Calendar/1  from  Clear  Systems 
formats  calendars  for  terminal  display 
or  printing  from  text  editor  entered  in 


no  special  order  or  format.  It  costs 
$60  and  runs  under  52K  CP/M-80. 
Reader  Service  No.  125. 
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DR.  DOBB’S  CLINIC 


by  D.  E.  Cortesi,  Resident  Intern 


A  Yodel  from  Yap 

John  Thayer  Jensen,  of  Yap,  TT, 
writes  us  as  follows.  “I  have  the  kiss  of 
death:  I  bought  an  IMSAI  VDP-80  and 
that  put  IMSAI  out  of  business.  So  the 
first  thing  is,  if  there  are  any  IMSAI  VDP- 
80  owners  out  there  who  will  write  me,  I 
can  share  a  partially  commented  disassem¬ 
bly  of  IMDOS’s  BDOS,  similar  disassem¬ 
blies  of  the  DIO  and  VIO  ROMs,  and  can 
sometimes  answer  questions  about  IMDOS 
and  IMSAI  hardware. 

“I  also  bought  a  now-obsolete  multi¬ 
tasking  operating  system  called  FAMOS 
from  MVT  Microcomputing.  They  never 
sold  any  more  (as  far  as  I  can  tell)  and 
while  they  make  a  token  effort  at  support, 
they  can’t  be  expected  to  do  much  —  and 
the  thing  doesn’t  work.  If  there  are  any 
FAMOS  users  reading  this,  I  have  next  to 
nothing  to  offer,  but  an  infinite  number 
of  questions  to  ask  someone! 

“It  would  be  wonderful  to  hear  from 
some  fellow  VDP-80  and/or  FAMOS 
users.  I  can’t  check  into  CBBSs,  can’t  go 
to  meetings,  can’t  phone  anyone.  We  have 
a  U.S.  zipcode,  proving  that  we  are  not  at 
the  end  of  the  world  (although  on  a  clear 
day,  you  can  see  it  from  here),  and  domes¬ 
tic  first-class  mail  will  reach  us  by  air.” 

If  you  would  like  to  correspond  with 
Jensen  in  his  lonely  outpost  (Yap  is  an 
island  in  the  mid -south  Pacific),  you  can 
write  to  him  at  P.O.  Box  358,  Yap,  TT 
96943. 

PC  Still  Backward 

In  March  we  expressed  our  puzzle¬ 
ment  at  the  results  of  printing  an  ASCII 
backspace  from  BASIC  in  the  IBM  PC. 
The  result  of 

PRINT  CHR$(8) 

is  precisely  nothing,  while  the  result  of 

PRINT  “wotizzit:”,CHR$(8) 
is  (as  we  described  it)  a  small  reverse- 
video  diamond  which  we  couldn’t  find  in 
any  manual. 

Several  readers  responded.  Randolph 
Fritz  of  Mahwah,  New  Jersey  and  Bob 
Taylor  of  Buffalo,  New  York  wrote  to 
point  out  that  the  complete  character  set 
is  shown  on  pages  C-12  and  C-13  of  the 
IBM  Technical  Reference,  and  it  includes 
the  one  we  couldn’t  find.  Robert  Pirko  of 
New  York  added  that  “The  funny  charac¬ 
ter  you  see  is  intended  to  be  a  reverse- 
video  circle.  For  the  graphics  adapter  in 
the  40-character  mode,  it  looks  roughly 
like  a  circle.  In  the  80-character  mode, 


the  width  is  cut  in  half  and  the  circle  does 
look  more  like  a  diamond.” 

David  Kellogg,  also  of  New  York, 
called  to  say  the  same,  and  added  that  if 
you  print  character  226,  the  Technical 
Reference  says  you  should  get  a  lower¬ 
case  gamma,  but  you  actually  get  an 
upper  case  gamma. 

OK.  The  whole  situation  is  very  con¬ 
fusing,  but  we  think  we  understand  it 
now.  Follow  us  through  this.  (1)  IBM,  for 
whatever  reason,  implemented  a  graphic 
symbol  for  every  byte  value  from  001  to 

254  inclusive,  leaving  only  000,  032,  and 

255  as  blank  or  null  displays.  The  bytes 
from  032  to  127  have  their  ASCII  sym¬ 
bols;  the  others  produce  unique  special 
characters.  (2)  The  PC’s  ROM  implements 
a  simple  dumb-terminal  function  (WRITE- 
TTY)  which  takes  ASCII  bytes  and  dis¬ 
plays  them.  It  implements  the  control 
characters  as  a  teletype  would,  including 
carriage  return  (CR),  line  feed  (LF),  and 
backspace  (BSP).  However,  WRITE-TTY 
does  not  implement  cursor  addressing  (as 
any  modern  terminal  should,  no  matter 
how  dumb). 

But  (3)  the  BASIC  interpreter  needs 
direct  cursor  addressing  for  its  screen 
editing,  so  it  calls  upon  the  more  primi¬ 
tive  routines  in  ROM.  These  routines  sup¬ 
ply  cursor  positioning  and  screen  output 
(SET-CPOS  and  WRITE-AC-CURRENT). 
Since  they  are  not  trying  to  emulate  a 
terminal,  they  treat  ASCII  control  char¬ 
acters  as  data.  A  control  character  like 
BSP,  sent  via  WRITE-AC-CURRENT,  will 
go  into  the  screen  display  as  a  symbol;  it 
will  not  have  its  standard  ASCII  effect. 

Then  (4)  the  BASIC  interpreter  also 
used  the  primitive  ROM  functions  to  im¬ 
plement  the  PRINT  statement;  thus  any 
character  written  via  PRINT  will  go 
straight  to  the  screen  as  a  symbol. 

Except  that  (5)  the  interpreter  wants 
to  supply  some  modicum  of  standard 
control  characters,  so  it  intercepts  BEL 
(and  toots  the  horn),  CR  (and  returns  the 
cursor),  TAB  (and  tabs  by  8),  LF  (and 
moves  the  cursor  down),  and  FF  (and 
clears  .the  screen).  In  effect,  it  does  the 
job  of  WRITE-TTY,  but  in  the  interpreter 
code.  It  should  intercept  BSP  as  well;  it 
apparently  does  so  when  the  cursor  is  at 
the  left  margin,  but  not  otherwise.  So  a 
backspace  at  the  left  margin  acts  like  a 
backspace  (doing  nothing),  but  once 
away  from  the  margin,  it  gets  through 
and  becomes  a  symbol.  This  appears  to  be 
a  bug  in  BASIC. 


Finally  (6)  the  interpreter  wants 
users  to  be  able  to  move  the  cursor  freely, 
so  not  only  does  it  implement  the  LO¬ 
CATE  verb,  it  also  intercepts  the  ASCII 
control  characters  US,  RS,  FS,  and  GS 
and  treats  them  as  commands  to  move 
the  cursor  in  the  four  cardinal  directions. 

The  net:  a  BASIC  programmer  has 
two  ways  to  position  the  cursor  (neither 
compatible  with  any  other  BASIC),  but 
lacks  both  a  standard  backspace  and  the 
nonstandard  symbols  of  bytes  028-031. 
Meanwhile,  the  user  of  another  high-level 
language  can  use  the  backspace  (since 
most  of  these  use  WRITE -TTY)  but  can¬ 
not  move  the  cursor.  This  is  how  your 
major  corporations  do  whatcha  call  your 
systems  analysis  and  design  stuff,  see? 


SuperKludge 

Nick  Hammond,  now  of  Torrens, 
Australia,  has  sent  us  a  lovely  kludge  for 
CP/M  2.2.  Here’s  what  he  says. 

“A  couple  of  months  ago,  I  was 
asked  to  modify  an  8-inch,  single-sided, 
single-density  CP/M  system  to  allow  a 
larger-than-standard  directory.  It  proved 
to  be  a  fairly  simple  mod  and  I  thought 
you  might  like  to  share  it  with  your 
readers. 

“A  standard  8 -inch,  single-density 
CP/M  diskette  has  a  file  directory  that 
will  hold  64  entries.  Since  each  16K  ex¬ 
tent  of  a  file  requires  one  entry,  this  may 
amount  to  less  than  64  actual  files. 
Given  the  maximum  data  storage  of  240K 
odd,  this  is  a  reasonable  number,  but 
occasions  will  arise  when  we  need  more. 
The  example  that  prompted  this  note  was 
a  need  to  fit  a  dBase  II  application  with  a 
large  number  of  command  files  onto  one 
disk,  leaving  the  second  free  for  data. 

“Fortunately,  CP/M  2.2  is  both  flexi¬ 
ble  and  well  thought-out,  and  expanding 
the  directory  can  be  done  relatively  sim¬ 
ply.  Two  things  must  be  done:  generation 
of  a  diskette  which  will  look  okay  to  both 
the  standard  and  modified  systems,  and 
insertion  of  a  two-byte  patch  to  modify 
the  BIOS  for  the  new  directory  size. 

“The  standard  directory  on  a  single - 
density  8 -inch  disk  occupies  the  first  two 
IK  blocks  after  the  system  tracks.  The 
modified  directory  will  occupy  the  first 
four,  and  we  therefore  need  to  reserve  the 
third  and  fourth  blocks.  If  this  is  not 
done,  the  directory  could  be  overwritten 
when  used  with  an  unmodified  BIOS,  and 
would  then  appear  full  of  garbage  when 
used  with  a  modified  one. 
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“We  can  reserve  the  extra  directory 
blocks  by  making  the  first  file  written  to 
disk  a  dummy,  full  of  E5  bytes.  To  the 
standard  system,  this  will  appear  as  a  nor¬ 
mal  file;  to  the  modified  system,  the  E5 
pattern  will  look  like  two  blocks  of  empty 
directory  space.  To  ensure  that  the  dummy 
file  occupies  the  third  and  fourth  blocks, 
it  must  be  written  under  a  standard  sys¬ 
tem  and  it  must  be  the  first  file  on  the 
diskette.  If  your  SYSGEN  procedure 
copies  hidden  files  to  the  new  disk,  the 
dummy  file  must  be  written  before  you 
SYSGEN  the  disk.  The  following  DDT 
session  illustrates  the  procedure. 

A  >  ddt 

DDT  VERS  2.2 

-fl00,900,e5  fill  2K  with  E5h 

-gO  exit  DDT 

A>  save  8  b:  empty  save  dummy  file 

A>stat  b:  empty  $sys  and  hide  it 

“CP/M  gets  its  information  on  direc¬ 
tory  size  from  the  Disk  Parameter  Block 
(DPB),  a  data  area  contained  in  the  BIOS. 
To  enlarge  the  directory  it  is  necessary  to 
alter  two  bytes  in  the  DPB.  The  first  is 
DRM,  a  count  one  less  than  the  number 
of  directory  entries.  The  second  is 
ALLOCO,  a  bit-map  of  the  disk  blocks 
reserved  for  the  directory. 

“The  DDT  session  that  follows  shows 
how  to  find  the  DPB  and  how  to  make  a 
small  command  file,  KLUDGE.COM,  to 
alter  it.  The  DPB  that  this  procedure  lo¬ 
cates  is  the  one  for  the  default  drive.  In 
most  systems  there  is  only  one  DPB  for 
each  disk  format  and  the  modification  will 
affect  all  drives.  If  it  doesn’t  on  yours, 
just  repeat  the  exercise  with  a  different 
drive  logged  in. 

A>  ddt 

DDT  VERS  2.2 

-alOO 

0100  mvi  c,lf 
0102  call  5 
0105  rst  7 
0106  . 

-glOO 
*0105 

-x  HL  has  the  address 

C0Z1M0E1 10  A=14  B=  ...  H  =  FE14  ... 
-hfel4  e  calculate  its  size 

FE22  FE06 

-dfel4fe22  dump  it  to  make  sure 

FE14  1A  00  03  07  00  F2  00  3F  00  CO  ... 
FE20  00  02  00  . . . 

-alOO 

0100  mvi  a,7f 
0102  sta  felb 
0105  mvi  a,f0 
0107  sta  feld 
010A  ret 
010B  . 

-g0 

A >  save  1  b:  kludge.com 


“After  running  KLUDGE,  the  direc¬ 
tory  will  have  space  for  128  entries,  and 
should  stay  that  way  until  the  next  cold 
boot,  which  overwrites  the  BIOS.  Some 
manufacturers  such  as  Osborne  have 
chosen,  for  reasons  best  known  to  them¬ 
selves,  to  rewrite  the  BIOS  at  warm  boot 
also,  contrary  to  CP/M  specifications.  On 
these  systems,  KLUDGE  will  have  to  be 
run  after  each  boot.”  [A  BIOS  that  sup¬ 
ports  multiple  formats  may  rebuild  the 
DPB  when  a  disk  is  selected  after  a  warm 
start  -  DEC.  ] 


A  Stack  of  Boots 

Aubrey  Hutchison  has  checked  in 
with  a  warning  for  users  of  the  California 
Computer  Systems  BIOS  supplied  with 
the  2422  disk  controller  board.  “After 
running  for  18  months,”  he  writes,  “I 
found  a  problem  that  was  bothering  me 
from  time  to  time.  At  times  when  using 
PIP,  the  machine  would  appear  to  hang 
up;  at  other  times  it  would  seem  to  PIP 
forever;  but  most  of  the  time  PIP  worked 
as  expected. 

“The  problem  turned  out  to  be  related 
to  the  CCS  boot  code  and  boot  ROM. 
The  stack  pointer  is  set  by  the  ROM  to  be 
the  top  of  RAM  —  56Kb  in  my  case,  since 
at  boot  time  the  top  8Kb  of  RAM  is 
banked  out.  When  the  ROM  enters  the 
cold-boot  routine  loaded  from  disk,  it 
leaves  the  stack  in  the  same  place.  The 
cold-boot  routine  doesn’t  change  it.  The 
CCS  BIOS  did  not  set  the  stack  pointer 
either  [if  sets  it  on  a  warm  boot  but  not  a 
cold  one  —  DEC ]  so  until  the  CP/M  CCP 
took  over,  the  stack  was  not  set  at  some 
other  location.  Since  the  BIOS  used  the 
stack  for  one  or  two  (maybe  three)  levels, 
the  stack  was  having  a  good  time  playing 
around  in  the  BDOS.  The  damage  must 
have  been  small  since  I  used  it  in  this  con¬ 
dition  for  18  months. 

“My  method  of  correcting  the  prob¬ 
lem  was  to  fix'  the  location  of  the  stack 
at  the  entry  to  the  cold-boot  routine.  I 
found  space  to  insert 

lxi  h,0100h 

sphl 

at  the  start  of  the  cold-boot  code  without 
changing  the  original  code.  The  same  thing 
could  be  done  in  the  BIOS  [<7f  label 
BOOT].” 

What  do  you  suppose  the  BDOS  has 
in  its  highest  two  or  three  words  that 
overwriting  them  would  cause  trouble, 
but  only  rarely? 

The  Intern’s  2.2  BIOS 

In  the  last  couple  of  columns  we 
talked  about  the  fancy  BIOS  we  built  for 
a  CP/M  2.2  system  with  banked  storage. 
We  have  CP/M  3  running  now,  and  in 
building  its  BIOS  we  had  to  pretty  much 
rip  up  the  new  2.2  BIOS  and  lay  it  down 


assemble  a  program 
to  locate  the  DPB 


execute  it 


assemble  a  program 
to  patch  the  DPB 
. . .  change  DRM  to  127 
...reserve  4  blocks 
...in  ALLOCO 


again.  It  seems  a  shame  to  let  such  a  pretty 
thing  die  so  soon,  but  we  really  have  no 
more  use  for  it.  And  who  else  would, 
unless  they  had  exactly  our  hardware 
configuration?  Or  unless  they  had  a  maso¬ 
chistic  desire  to  read  approximately  95 
pages  of  heavily  commented  Z80  assem¬ 
bly  code. . .  . 

If  you  have  such  a  masochistic  desire, 
you  can  have  a  copy  of  our  2.2  BIOS 
for  your  bedside  reading.  Send  your  own 
8-inch,  single-density  diskette  and  a 
sturdy  self-addressed,  postage-paid  disk¬ 
ette  mailer,  and  we’ll  duplicate  the  source 
files  onto  it.  Address  the  package  to  “The 
Intern’s  2.2  BIOS”  c/o  PCC,  P.O.  Box  E, 
Menlo  Park,  CA  94025.  Note  that  you 
should  not  expect  to  actually  use  this 
code.  If  you  have  any  idea  for  doing  so, 
be  aware  that  it  needs  RMAC  and  LINK; 
it  comes  with  minimal  documentation; 
and  it  carries  absolutely  no  warranty  or 
support  of  any  kind. 

CP/M  Plus  —  Sector  Buffering 

The  CP/M  3  (or  CP/M  Plus)  BDOS 
buffers  disk  sectors  in  storage  in  an  at¬ 
tempt  to  speed  up  processing.  The  attempt 
may  be  successful  in  some  cases  (we 
haven’t  tried  any  direct-access  I/O  yet), 
but  the  BDOS  uses  its  sector  buffers  in  a 
way  that  is  far  from  optimal  for  sequential 
I/O.  This  is  demonstrated  by  some  experi¬ 
ments  we  made  recently. 

A  CP/M  3  BIOS  for  a  banked  system 
supplies  the  address  of  two  words  in  stor¬ 
age  in  the  Disk  Parameter  Header  that  it 
returns  from  a  SELDSK  call.  These  are 
the  anchors  of  two  chains  of  Buffer  Con¬ 
trol  Blocks  (BCBs).  Each  BCB  describes  a 
buffer  that  the  BDOS  may  use  to  save  a 
disk  sector  (a  physical  sector,  not  a  128  - 
byte  logical  sector).  There  are  separate 
chains  for  directory  and  data  sectors. 
According  to  the  CP/M  3  System  Guide, 
page  8,  “In  a  banked  environment,  CP/M 
3  maintains  a  cache  of  deblocking  buffers 
and  directory  records  using  a  Least 
Recently  Used  (LRU)  buffering  scheme.” 
And  on  page  46,  “In  general,  you  can 
enhance  the  performance  of  CP/M  3  by 
allocating  more  BCBs.” 

Always  anxious  to  improve  perfor¬ 
mance,  we  gave  CP/M  3  a  grand  total  of 
71  sector  buffers,  each  one  a  kilobyte, 
spread  over  our  four-bank  system.  Seventy- 
one  kilobytes  of  data  space  (plus  another 
8K  of  directory  buffers)  is  not  exactly  a 
SemiDisk,  but  it’s  a  lot  more  buffers  than 

(Continued  on  page  89) 
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Fast  Divisibility  Algorithms 


It  is  well  known  that  the  lowest  digit  of 
an  integer,  if  not  1,  3,  7,  or  9,  suffices 
to  establish  divisibility  by  2,  5,  or  10. 
Algorithms  for  divisibility  by  other  small 
integers  (such  as  3,  7,  9,  or  11)  are  not 
common  knowledge.  They  require  infor¬ 
mation  from  all  the  digits  of  the  number, 
and  are  too  complex  to  be  part  of  ele¬ 
mentary  arithmetic  but  too  trivial  for  the 
mathematical  elite.  Even  the  “obviously 
divisible”  integers  contain  useful  informa¬ 
tion  in  the  next-to-last  digit.  E.g.,  num¬ 
bers  ending  in  5  are  divisible  by  25  if  the 
preceding  digit  is  2  or  7,  while  numbers 
ending  in  0  are  divisible  by  25  if  the  pre¬ 
ceding  digit  is  0  or  5.  Numbers  ending  in 
2  or  6  are  divisible  by  4  if  the  preceding 
digit  is  odd  —  if  it  is  even,  the  number  has 
only  a  single  factor  of  2 ;  the  opposite  is 
true  of  numbers  ending  in  0,  4,  or  8. 

The  algorithm  for  divisibility  by  3  or 
9  is  relatively  simple.  It  requires  informa¬ 
tion  from  all  the  digits,  but  is  indepen¬ 
dent  of  the  order  of  the  digits.  It  calcu¬ 
lates  the  “reduced  digit-sum”  by  adding 
all  the  digits;  whenever  this  becomes  10 
or  more,  1  is  added  to  the  low  digit  and 
the  high  digit  is  discarded  so  that  the 
sum  is  always  a  number  from  1  to  9.  If 
the  final  reduced  sum  is  9,  the  number  is 
divisible  by  9.  If  it  is  3  or  6,  the  number 
has  a  single  factor  of  3.  E.g.,  the  number 
123456789  has  a  reduced  sum  of  9  and 
so  is  divisible  by  9.  This  is  true  of  all  the 
possible  permutations  of  these  digits,  and 
also  true  for  12345678  and  all  its  permu¬ 
tations.  However,  1234567  has  a  reduced 
sum  of  1  and  so  cannot  be  divided  by  3, 
nor  can  any  of  its  permutations.  The  pres¬ 
ence  of  zeroes  within  the  numerical  se¬ 
quence  does  not  affect  the  truth  of  the 
algorithm;  e.g.,  45,  405,  4005  all  are 
multiples  of  9,  and  so  of  45. 

The  algorithm  for  divisibility  by  11  is 
somewhat  more  complex,  since  it  depends 
on  the  order  of  the  digits  (only  a  fraction 
of  the  possible  permutations  being  multi¬ 
ples  of  11).  It  requires  the  calculation  of 
two  digit-sums.  The  “high”  sum  is  that  of 
the  first,  third,  fifth,  etc.  digits;  the  “low” 
sum  is  that  of  the  second,  fourth,  sixth, 
etc.  digits.  Within  each  of  these  sets,  how¬ 
ever,  the  order  of  the  digits  does  not 
affect  the  truth  of  the  algorithm  since  this 
requires  only  that  the  difference  between 
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the  two  sums  be  a  multiple  of  11,  or  0. 
The  difference  will  always  be  0  if  each 
sum  is  reduced  by  1 1 ,  though  it  is  simpler 
to  reduce  only  the  difference,  in  one  step, 
if  it  is  not  0.  An  example  is  the  number 
12435687  with  both  high  and  low  digit- 
sums  equal  to  18,  and  so  divisible  by  11. 
If  one  adds  the  two  sums,  the  value  36 
reduces  to  9,  so  the  number  is  divisible 
by  99.  Which  set  is  “high”  does  not  mat¬ 
ter;  e.g.,  21346578  is  also  divisible  by  99, 
and  of  course  also  by  2.  Though  more 
complex,  this  algorithm  can  test  divisibili¬ 
ty  by  3,  9,  or  11  in  one  operation.  For 
gigantic  numbers,  the  digit-sums  can  be 
reduced  by  99  since  this  is  a  multiple  of 
both  9  and  11  —  if  a  sum  reaches  100 
it  reduces  to  1 ,  etc. 

These  algorithms  are  valid  for  num¬ 
ber  bases  other  than  decimal,  although 
this  alters  the  factoring  integers.  In  octal, 
successive  multiples  of  the  highest  digit 
(7)  are  16,  25,  34,  43,  etc.,  so  that  num¬ 
bers  of  any  size  will  yield  a  total  reduced 
sum  of  7,  while  successive  multiples  of  its 
base  (8)  +  1  (=  9)  are  11,  22,  33,  etc.  In 
hexadecimal  (base  16),  the  total  reduced 
sum  of  numbers  factorable  by  its  highest 
digit  (F,  =  15  decimal)  must  always  be 
F  (e.g.,  IE,  2D,  3C,  etc.),  while  the 
“elevenish”  series  (11,  22,  33,  etc.)  has 
all  multiples  of  decimal  17. 

As  in  the  decimal  “base  minus  1” 
algorithm,  in  which  reduction  by  9  re¬ 
veals  multiples-of-3  when  the  reduced 
sum  is  3  or  6,  so  in  hexadecimal  does  a 
reduced  sum  of  3,  6,  9,  or  12  reveal  divisi¬ 
bility  by  3  (but  not  5),  while  a  reduced 
sum  of  5  or  A  (decimal  1 0)  reveals  divisi¬ 
bility  by  5  (but  not  3).  Only  in  decimal 
do  multiples  of  5  always  have  0  or  5  as 
the  lowest  digit.  The  general  rule  (at  least 
for  bases  that  are  even  numbers)  is  that 
numbers  divisible  by  the  digit  that  is  half 
the  base  always  end  in  0  or  that  digit. 

Divisibility  by  7  can  now  be  seen  to 
require  a  general  “base  minus  3”  algo¬ 
rithm,  that  in  octal  would  recognize  divis¬ 
ibility  by  5  and  in  hexadecimal  divisibility 
by  13.  I  have  only  studied  the  algorithm 
for  decimal  notation.  It  is  even  more 
complex  than  divisibility  by  1 1,  requiring 
not  only  calculation  of  a  similar  high  and 
low  pair  of  digit-sums,  but  positional 
“weighting”  of  each  digit.  The  order  of 
the  digits  in  each  set  is  significant.  Rela¬ 
tively  few  permutations  within  each  set 
retain  divisibility  by  7,  since  only  digits 
with  the  same  weighting  factor  can  be 
interchanged.  Weighting  involves  multi¬ 
plication  by  1  (i.e.,  no  change)  for  the 


first,  fourth,  seventh,  etc.  digit  (reading 
the  number  from  left  to  right),  multipli¬ 
cation  by  2  for  the  second,  fifth,  eighth, 
etc.  digit,  and  multiplication  by  4  for  the 
third,  sixth,  ninth,  etc.  digit.  However, 
digits  can  be  reduced  by  7,  to  a  pseudo- 
heptal  notation;  i.e.,  7  becomes  0,  8  be¬ 
comes  1 ,  and  9  becomes  2.  Also,  the  prod¬ 
uct  of  a  digit  by  its  weighting  factor  can  be 
reduced  by  7 ;  e.g.,  if  the  digit  is  6  and  its 
factor  is  4,  the  product  (24  =  3  *7  +  3) 
can  be  replaced  by  3.  Since  such  repeti¬ 
tious  calculation  would  slow  the  algo¬ 
rithm  down,  the  operation  of  replacing 
each  digit  by  its  weighted  and  reduced 
digit  can  be  done  by  the  following  look¬ 
up  table: 

Decimal  Digit  to  be  “Replaced” 


Order 

1 

2 

3 

4 

5 

6 

7 

8 

_9 

1 

1 

2 

3 

4 

5 

6 

0 

1 

2 

2 

2 

4 

6 

1 

3 

5 

0 

2 

4 

3 

4 

1 

5 

2 

6 

3 

0 

4 

1 

For  example,  the  algorithm  alters  the 
number  421589637  to  444521660,  which 
has  16  for  both  its  high  and  low  digit- 
sums.  The  original  number  is  therefore 
divisible  by  7  since  this  requires  that  the 
difference  be  either  0  (as  in  this  case)  or 
also  a  multiple  of  7.  Since  this  number 
also  happens  to  be  divisible  by  9,  it  is  di¬ 
visible  by  63.  Another  example  is  10101, 
which  alters  to  10402  with  a  high  digit- 
sum  of  7  and  a  low  of  0,  revealing  divisi¬ 
bility  by  7  and  (since  the  total  unaltered 
digit-sum  is  3)  by  21. 

All  these  divisibility  algorithms  in¬ 
volve  no  actual  division.  They  only  deter¬ 
mine  whether  division  by  the  small  prime 
being  tested  is  possible,  and  can  do  this 
relatively  quickly  even  for  gigantic  num¬ 
bers  by  reducing  them  to  much  smaller 
numbers  that  retain  the  same  divisibility. 
A  high  proportion  (56.6%)  of  very  large 
random  numbers  ending  in  1,3,  7,  or  9 
will  be  divisible  by  3,  7,  or  1 1  and  so  can 
be  proved  to  be  non- prime.  Algorithms 
for  divisibility  by  higher  small  primes  (13, 
17,  19,  etc.)  could  surely  be  devised,  but 
would  “sieve  out”  ever- decreasing  frac¬ 
tions  of  non-primes  at  an  ever-increasing 
cost  in  complexity.  However,  one  never 
knows  when  exotic  algorithms  may  prove 
useful,  if  only  as  clues  to  far  more  power¬ 
ful  ones. 

One  human-interest  element  is  that  I 
did  a  casual  search  for  these  algorithms  in 
various  math  books,  in  the  certainty  that 
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they  were  known,  but  failed  to  find  them. 
Rediscovering  the  3-6-9  and  the  1 1  algo¬ 
rithms  —  by  simple  inspection  of  the  digit 
sequence  of  small  multiples  —  was  child’s 
play.  Subsequently  I  found  these  algo¬ 
rithms  on  pages  25-27  of  the  VNR  Con¬ 
cise  Encyclopedia  of  Mathematics,  re¬ 
cently  published  (or  reprinted)  by  Van 
Nostrand  Reinhold.  This  is  the  work  of 
East  German  mathematicians  and  presents 
a  few  uses  in  detection  of  errors  in  com¬ 
plex  calculations.  It  omits  the  divisibility- 
by-7  algorithm,  though  I’m  certain  this 
was  also  discovered  (probably  more  than 
once)  long  ago.  I  found  it  less  obvious 
than  the  simpler  algorithms.  Its  compu¬ 
tational  drudgery  would,  in  the  pre¬ 
computer  era,  have  discouraged  its  use. 
Even  the  extension  to  other  number  bases 
has  probably  been  done  before,  though 
like  other  things  the  elite  see  as  trivial,  it 
has  been  forgotten!  The  VNR  Encyclo¬ 
pedia  reference  pointed  out  something  I 
had  ignored,  that  what  I’ve  called  the 
“reduced  sum”  is  not  useless  even  when 
non- divisibility  is  found,  since  it  is  then 
the  remainder  that  would  be  obtained 
if  the.  division  were  actually  done.  Per¬ 
haps  the  divisibility-by-3  algorithm  could 
be  used  to  test  random-number  genera¬ 
tors,  since  1/3  of  a  fairly  large  sample  of 
large  numbers  ought  to  be  divisible  by  3, 
1/3  should  have  a  remainder  of  1,  and 
1/3  a  remainder  of  2. 
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B-Tree  ISAM  Concepts 


How  do  you  retrieve  random  informa¬ 
tion  quickly  from  a  large  disk  file? 
Every  programmer  who  has  written 
software  for  business  has  had  to  deal  with 
this  problem.  Fortunately,  computer  sci-  ■ 
entists  have  refined  an  elegant  and  simple 
method  for  retrieving  information  called 
a  B-Tree.  The  objective  of  this  article  is 
to  explain  the  principles  and  techniques 
involved  in  a  B-Tree. 

Why  ISAM? 

With  current  hardware  technology, 
about  the  only  way  to  quickly  retrieve 
information  out  of  a  disk  file  is  using  an 
indexing  method.  There  are  many  meth¬ 
ods  of  indexing  data.  ISAM,  Indexed 
Sequential  Access  Method,  has  become 
very  popular  for  use  in  many  business 
systems.  It  allows  the  information  to  be 
retrieved  randomly  by  data  value  (indexed) 
and  in  sorted  order  (sequential)  using  just 
one  index  file.  This  dual  ability  is  what 
distinguishes  ISAM  from  other  methods, 
such  as  Hashing.  While  there  are  many 
ways  to  implement  an  ISAM  index,  the 
B-Tree  is  generally  accepted  as  being  the 
current  “state  of  the  art.” 

General  ISAM  Principles 

An  ISAM  file  is  a  file  composed  of 
individual  pieces  of  information  called 
“keys.”  A  key  is  an  ASCII  string  repre¬ 
senting  some  value  in  a  data  record.  The 
index  is  arranged  in  such  a  way  that  keys 
can  be  retrieved  randomly  and  sequen¬ 
tially,  along  with  their  associated  data 
record  numbers.  There  are  a  number  of 
different  schemes  designed  to  serve  this 
purpose,  a  B-Tree  being  only  one.  To  bet¬ 
ter  appreciate  the  B-Tree,  we  will  look  at 
an  older  method,  called  the  binary  tree. 

A  tree  structure  is  called  such  because 
if  all  the  search  paths  are  drawn  out,  they 
resemble  an  inverted  tree  as  shown  in 
Figure  1  (at  right).  The  search  starts  at 
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the  root  and  progresses  down  the  tree  un¬ 
til  it  possibly  reaches  the  bottom  (called 
leaves,  or  leaf  level).  Note  also  in  Figure  1 
that  from  any  point  in  the  tree,  there  are 
two  paths  to  the  next  lower  level,  hence 
the  term  “binary  tree.”  In  a  simple  binary 
tree,  each  key  is  stored  in  an  individual 
record,  or  node.  Each  node  also  has  two 
pointers  to  other  nodes.  These  pointers 
are  what  make  up  the  search  paths  through 
a  tree. 

A  search  through  a  binary  tree  is,  on 
a  basic  level,  a  simple  procedure.  To  find 
the  key  “G,”  it  is  first  compared  to  the 
key  in  the  root  node.  If  “G”  matches, 
then  the  search  is  successful.  Otherwise,  a 
decision  must  be  made,  that  is,  where  to 
go  next.  If  “G”  is  smaller  than  the  root 
node,  then  the  path  to  the  left  is  taken.  If 
“G”  is  larger  than  the  root,  then  the  path 
to  the  right  is  taken.  The  path  is  followed 
and  the  new  node  is  read.  “G”  is  then 
compared  to  the  key  in  this  node  as  be¬ 
fore,  and  the  appropriate  action  is  taken. 
The  search  continues  until  either  “G”  is 
found,  or  a  leaf  node  is  unsuccessfully 
evaluated. 

As  long  as  the  nodes  are  kept  in 
memory,  the  binary  search  is  an  efficient 
method.  Once  the  nodes  are  stored  on  the 
disk,  however,  the  performance  quickly 
degrades  because  of  the  large  number  of 
disk  accesses  required. 

Other  problems  can  also  arise  when 
keys  are  inserted.  This  can  have  the  effect 
of  making  the  tree  unbalanced  -  that  is, 
some  search  paths  being  longer  than 
others.  This  requires  that  the  search  and 


insertion  algorithms  be  aware  of  this 
possibility,  and  subsequently  these  proce¬ 
dures  become  much  more  complicated. 

The  Basic  B-Tree 

The  problems  with  the  binary  tree  in 
large  disk-based  filing  systems  gave  an  in¬ 
centive  for  researchers  to  look  for  some¬ 
thing  better.  In  the  late  1960s  a  number 
of  people  independently  designed  such  a 
method  called  a  B-Tree.  Apparently  the 
reason  for  the  name,  B-Tree,  seems  to  be 
the  fact  that  R.  Bayer,  then  at  Boeing 
Scientific  Research  Labs,  was  one  of  the 
pioneers  of  the  method  (“Bayer-Tree”).1 

Figure  2  (page  19)  shows  an  example 
of  the  B-Tree  format.  The  most  obvious 
difference  between  a  binary  tree  and  a 
B-Tree  is  that  from  any  one  node  there 
can  be  more  than  two  paths  to  the  next 
node.  This  has  the  effect  of  allowing 
many  more  keys  in  each  node  of  a  B-Tree 
than  with  a  binary  tree.  For  instance,  a 
binary  tree  with  ten-byte  keys,  holding 
one  million  keys,  could  take  as  many  as 
twenty  node  searches  to  find  any  one 
key.  A  B-Tree  with  the  same  conditions 
(assuming  ten  keys  per  node)  would  at 
the  most  take  five  node  searches.  In  the 
case  where  node  searches  correspond  to 
disk  accesses,  the  search  time  difference 
is  obviously  dramatic. 

Searching  a  B-Tree 

To  find  a  key  in  a  B-Tree,  the  first 
step  is  to  look  at  the  root  node.  In  the 


Figure  1.  A  Binary  Tree 
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example  shown  by  Figure  2,  there  are  a 
maximum  of  three  keys  in  each  node.  To 
decide  what  to  do,  a  process  called  scan¬ 
ning  is  used.  This  involves  sequentially 
looking  at  each  key  in  the  node  (note 
they  are  stored  in  ASCII  sequence)  and 
stopping  when  either  a  matching  key  is 
found  (in  this  case,  the  search  is  success¬ 
ful,  and  it  ends)  or  a  higher  key  is  found. 
If  no  match  is  found,  then  a  decision 
must  be  made. 

Take,  for  example,  a  search  for  the 
key  “L.”  By  scanning  the  root  node  in 
Figure  2,  we  find  that  there  is  no  match¬ 
ing  key.  We  therefore  must  follow  a  pointer 
to  the  next  lower  level.  The  pointer  to 
follow  is  the  one  which  sits  where  the  key 
“L”  would  be  if  it  existed  in  the  node. 
In  this  case  we  would  follow  the  middle 
pointer  to  the  next  lower  node.  This 
node  is  then  read  and  the  same  procedure 
is  followed.  This  continues  until  either 
the  key  is  found,  or  a  leaf  node  is  unsuc¬ 
cessfully  scanned. 


Inserting  into  a  B-Tree 

Note  that  since  we  must  determine 
where  the  key  would  sit  if  it  existed  in 
the  node,  we  now  have  the  needed  infor¬ 
mation  to  insert  the  key.  Insertion  into  a 
B-Tree  uses  the  search  already  described. 
Then  the  key  is  simply  inserted  into  the 
node  where  it  should  be.  Note  that  keys 
are  always  inserted  into  leaf  nodes  (an 
insertion  depends  not  on  finding  the  key, 
but  on  finding  a  place  for  it).  Since  an  un¬ 
successful  search  always  ends  at  the  leaf 
level,  then  all  keys  will  be  inserted  there. 

If  the  node  into  which  the  key  is  to 
be  inserted  is  full,  then  a  split  occurs.  The 
original  node  and  the  new  key  are  divided 
up  into  two  new  nodes.  Since  there  is 
now  a  new  node,  a  pointer  to  the  new 
node  must  be  inserted  into  the  level 
above.  Usually  the  middle  key  of  the  two 


new  nodes  is  brought  up  to  the  next  level 
to  be  used  as  a  separator.  If  the  node 
above  is  also  full,  then  it  too  might  be 
split.  This  can  continue  up  to  the  root.  If 
a  split  of  the  root  node  occurs,  a  new 
root  node  is  created  so  that  the  tree 
becomes  one  level  higher. 

A  B-Tree  by  nature  is  always  a  bal¬ 
anced  tree.  Since  all  node  expansions  are 
done  on  the  same  level,  the  tree  never 
gets  unbalanced.  An  insertion  will  never 
increase  the  search  path  to  one  leaf  node 
and  not  the  others. 

Deletion  of  a  key  is  simply  finding 
the  key  and  taking  it  out  of  the  node.  If  a 
key  doesn’t  reside  in  a  leaf,  then  a  new 
key  must  take  its  place  to  provide  the 
same  paths  as  the  deleted  key.  This  new 
key  is  found  by  getting  the  next  key  in 
sequence  from  the  deleted  key. 

As  stated  before,  the  search  time  in  a 
B-Tree  is  much  more  efficient  than  in  a 
similar  binary  tree  when  stored  on  disk. 
Sequential  processing  in  a  B-Tree  is  not 
so  easy,  however.  Because  the  keys  are 
distributed  between  all  levels  of  the  tree, 
keys  must  be  retrieved  by  following  the 
links  up  as  well  as  down  the  tree,  working 
from  the  left  to  right.  This  becomes 
awkward  and  slow.  Try  it  by  hand  using 
Figure  2  and  you  will  quickly  see  why. 

If  the  sequential  processing  of  a 
B-Tree  could  be  improved  while  retain¬ 
ing  the  random  search  efficiency  and 
balanced  nature,  we  would  have  a  much 
better  method. 


The  B+Tree 

This  brings  us  to  one  of  the  most 
important  variants  of  the  B-Tree  called 
the  B+Tree.  Figure  3  (page  21)  shows  an 
example  of  the  B+Tree  format.  In  a 
B+Tree,  all  the  keys  are  stored  in  leaf 
nodes.  The  upper  levels  simply  provide 
pointers  to  the  next  lower  level,  and  so 


on  until  the  leaf  level  is  reached.  In  addi¬ 
tion,  all  the  leaves  are  linked  together. 
What  we  have,  in  effect,  is  a  tree  which 
provides  a  B-Tree  type  of  path  to  the 
proper  position  in  a  sequential  list  of  the 
keys. 

Since  all  the  keys  reside  on  the  leaf 
level,  sequential  processing  is  now  very 
easy  as  each  key  is  linked  together  sequen¬ 
tially  in  the  leaf  nodes.  This  gives  the 
B+Tree  the  desired  additional  characteris¬ 
tics  of  an  ISAM  while  retaining  the  sim¬ 
plicity  of  a  normal  B-Tree. 

The  B+Tree  search  uses  the  upper 
levels  as  a  roadmap  to  the  next  level,  and 
it  is  only  until  a  leaf  is  reached  that  the 
key  is  actually  looked  for.  Therefore,  all 
searches  use  the  same  number  of  node 
reads.  Although  this  guarantees  that  every 
search  will  be  a  “worst  case”  of  a  normal 
B-Tree,  we  have  seen  that  this  worst  case 
is  very  good  under  most  circumstances.  In 
addition,  since  all  searches  take  approxi¬ 
mately  the  same  amount  of  time,  a  high 
degree  of  consistency  is  achieved,  which 
can  have  its  benefits  in  a  real-world 
situation. 

One  nice  benefit  of  the  B+Tree 
structure  is  that  since  the  upper  levels  are 
just  pointers,  a  delete  doesn’t  have  to 
worry  about  revising  pointers  (deletes 
only  operate  on  leaves  which  have  no 
pointers). 

Key  searching  and  insertion  methods 
are  basically  the  same  as  in  a  normal 
B-Tree.  The  specific  B+Tree  we  imple¬ 
mented  uses  a  scheme  which  uses  the  high 
key  from  the  left  node  to  provide  a  sepa¬ 
rator  (located  in  the  index  node  above) 
between  the  left  node  and  the  right  node. 
For  example,  in  Figure  3,  a  search  for  the 
key  “H”  would  produce  the  following. 
First,  “H”  is  compared  to  the  first  key  in 
the  root  node.  Since  “H”  is  less  than  “I” 
the  search  proceeds  by  reading  the  next 


Leaves 


Figure  2.  A  B-Tree 
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lower  node  using  the  left-most  pointer. 
Then  “H”  is  compared  with  the  first  key 
in  the  lower  node.  Since  “H”  is  not 
smaller  than  or  equal  to  “C,”  we  must 
look  at  the  next  key.  Again,  since  “H”  is 
not  smaller  than  or  equal  to  “F,”  we 
move  on  to  the  next  key.  The  next  key  is 
“I.”  “H”  is  smaller  than  “I.”  Since  “I” 
represents  the  largest  value  stored  in  the 
node  its  left  pointer  points  to,  we  follow 
that  pointer. 

Splits  also  use  this  same  high-key 
logic.  At  split  time,  the  high  key  is  taken 
from  the  left  node  and  it  is  then  inserted 
(with  a  pointer  to  the  right  node  of  the 
split)  in  the  index  node  above  (see 
Figures  4a  and  4b  on  page  21). 

One  thing  should  be  mentioned 
about  the  B+Tree.  Since  all  the  keys  are 
in  leaves,  the  nodes  above  represent  an 
additional  overhead  not  found  in  the 
basic  B-Tree,  which  uses  only  key  values 
in  its  tree.  With  the  advent  of  inexpensive 
mass  storage,  though,  a  slight  bit  more 
storage  space  taken  up  is  well  worth  the 
many  benefits  a  B+Tree  has  to  offer. 

B -Trees  on  Micros 

Many  implementations  of  the  B-Tree 
ISAM  have  been  created.  For  example, 
IBM  uses  a  variant  of  the  B-Tree  for  their 
mainframe  computers  called  “VSAM.” 
More  recently,  the  B-Tree  ISAM  tech¬ 
niques  have  been  applied  to  microcom¬ 
puter  applications.  For  example,  dBase  II 
uses  a  B-Tree  method  for  indexing.  Also, 
a  number  of  companies  have  developed 
B-Tree  subroutine  products  for  micro¬ 
computers.  These  subroutines  can  be 
added  to  an  application  being  developed. 
The  application  programmer  uses  call 
statements  to  the  indexing  functions  built 
into  the  B-Tree  subroutine  without  hav¬ 
ing  to  be  concerned  with  all  the  details  of 
how  it  works. 

B-Tree  implementations  have  been 
produced  to  support  a  wide  variety  of 
languages.  The  authors  have  developed  a 
version  written  in  Forth.  Other  lan¬ 
guages  supported  by  various  B-Tree 
packages  include  BASIC,  Pascal,  C, 
COBOL,  Fortran,  and  others. 

For  the  programmer  interested  in 
creating  a  B-Tree  “from  scratch,”  the 
references  for  this  article  will  be  helpful. 
These  references  provide  more  details 
about  B-Tree  techniques  and  the  many 
subtle  variations  possible  in  designing  a 
B-Tree  ISAM. 

The  authors  have  implemented  B-Tree 
ISAM  technology  in  a  Forth  utility  called 
INDEX+.  Written  for  Laboratory  Micro¬ 
systems  Forth,  the  package  includes  fully 
documented  source  code  and  a  manual 
which  includes  tutortials  on  B+Tree  tech¬ 
nology  and  use  of  the  utility.  For  more 
information,  contact  Laboratory  Micro¬ 
systems. 
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CPfM  BDOS  and 
BIOS  Calls  for  C 


Ef  you  should  want  to  write  CP/M  utili¬ 
ties  in  C,  you  will  probably  need  facil¬ 
ities  to  access  the  BDOS  (Basic  Disk 
Operating  System)  and/or  the  BIOS  (Basic 
Input/Output  System).  Many  C  compilers 
for  CP/M  do  not  include  such  functions, 
and  several  of  those  which  exist  have 
severe  limitations,  in  that  they  may  not 
return  proper  values  in  all  cases. 

The  two  functions  bdos()  and  bios() 
described  here  will  enable  you  to  incor¬ 
porate  direct  BDOS  and/or  BIOS  calls  in 
programs  written  in  C.  Please  note  that 
programs  that  call  bdos()  or  bios()  will 
not  be  portable  beyond  CP/M  and  the 
8080  and  Z80  series  CPUs. 

bdos()  and  biosQ  were  originally 
written  for  the  C/80  compiler  from  The 
Software  Toolworks,  but  they  will  also 
compile/assemble/work  with  other  com¬ 
pilers  which  push  arguments  on  the  stack 
in  a  non -reversed  order  before  calling  a 
function.  Such  C  compilers  include  Small- 
C  and  most  of  its  derivatives.  bdos()  and 
biosO  have  been  tested  to  work  properly 
with  both  The  Software  Toolworks  C/80 
and  The  Code  Works  CW/C  compiler. 

bdos ( ) 

The  bdosQ  function  sets  machine 
register  C  to  the  function  number  speci¬ 
fied  in  funct,  and  the  register  pair  DE  to 
the  value  given  in  arg,  and  initiates  a  call 
to  BDOS.  The  function  number  may  be 
specified  numerically  or  symbolically. 
No  checking  of  the  arguments  is  done. 

If  funct  is  either  RETVN  (12), 
RETLV  (24),  GETAA  (27),  GETROV 
(29)  or  GETDPA  (31),  bdosQ  returns 
the  value  remaining  in  register  pair  HL  on 
return  from  BDOS.  For  all  other  BDOS 
functions,  bdosQ  returns  the  value  in  A, 
with  sign  extension.  In  this  way,  BDOS 
error  (255  or  FF(hex))  is  returned  as  -1. 

bios  ( ) 

The  bios()  function  sets  machine 
register  pair  BC  to  the  value  given  in  argl, 
and  the  register  pair  DE  to  the  value  given 
in  arg2,  and  initiates  the  appropriate 
BIOS  call  by  transferring  control  to  the 
BIOS  jump  vector  entry  point  specified  in 
funct.  This  entry  point  may  be  specified 
numerically  or  symbolically.  No  checking 
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of  the  arguments  is  done. 

If  funct  is  either  SELDSK  (9)  or 
SECTRAN  (16),  bios()  returns  the  value 
remaining  in  the  HL  register  after  execu¬ 
tion  of  the  BIOS  call;  otherwise  it  returns 
the  value  remaining  in  register  A  on  re¬ 
turn  from  BIOS,  with  sign  extension. 

Note  that  you  must  specify  all  three 
arguments  in  the  biosQ  function.  If  you 
do  not  need  the  last  one,  you  must  set  it 
to  0  or  any  other  value. 

Installation 

You  may  type  the  source  code  in 
Listing  1  (page  24)  into  a  file  called 
CPMCALL.C.  To  use  bdosQ  or  biosQ 
in  a  C  source  file,  you  must  #include 
“CPMCALL.C”  in  that  file. 

A  simple  example  on  how  to  use 
bdosQ  and  biosQ  is  shown  in  Listing  2 
(page  27).  In  this  example,  bdosQ  is  used 
to  get  the  current  disk  and  biosQ  is  used 
to  print  it  on  the  console.  You  may  use 
this  example  to  test  that  you  have  in¬ 
stalled  bdosQ  and  biosQ  correctly  on 
your  system.  When  run,  the  program 
should  write  the  uppercase  character 
corresponding  to  the  current  (logged) 
disk  drive  on  the  console.  Log  onto  dif¬ 
ferent  drives  and  check  that  the  program 
writes  out  the  correct  letter. 

Normally  it  is  not  advisable  to  do 
input/output  via  biosQ  or  bdosQ  (as 
done  with  biosQ  in  the  example),  if  this 
can  be  done  via  other  conventional  C 
functions,  such  as  putcharQ. 

In  order  to  be  compatible  with  code 
for  other  compilers  which  do  offer  the 
same  functions  (e.g.,  SuperSoft’s  C  com¬ 
piler),  you  should  refer  symbolically  to 
the  bdosQ  and  biosQ  function  numbers 
(as  shown  in  the  listings)  and  never  use 
numbers  directly.  The  reason  for  this  is 
that  other  compilers  may  not  use  the 
same  numerical  values  for  bios()  function 
numbers  as  used  in  this  version  of  biosQ. 

You  may  want  to  delete  (or  “com¬ 
ment  out”)  all  the  #define  macros  which 
will  not  be  used,  so  that  they  will  not 
occupy  unnecessary  space  in  the  com¬ 
piler’s  macro  substitution  table. 

After  compilation,  bdosQ  and  biosQ 
will  assemble  under  CP/ M’s  ASM,  The 
Software  Toolworks’  AS,  and  most  other 
8080  assemblers.  Both  functions  may  be 
assembled  for  nonstandard  versions  of 
CP/M  by  changing  the  CPBASE  equate 
from  0  to  the  required  value. 

If  you  should  want  to  delete  the 
bdosQ  function  and  make  a  separate 
function  of  biosQ  only,  you  need  to 


include  the  CPBASE  equate  in  front  of 
the  biosQ  assembly  code.  To  use  bdosQ 
and  biosQ,  refer  to  the  CP/M  Interface 
Guide  and  the  CP/M  Alteration  Guide. 

A  final  warning:  You  should  avoid 
direct  CP/M  calls  whenever  possible. 
Even  though  they  enable  you  to  do  won¬ 
derful  things  in  CP/  M,  they  will  limit  the 
portability  of  your  programs. 

The  code  may  be  copied,  used,  and 
distributed  by  anyone,  commercially  or 
otherwise,  provided  the  contribution 
notice  is  included. 

(Listings  begin  on  page  24) 
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BDOS  and  BIOS  Calls  for  C 

Listing  One  (Text  begins  on  page  22) 


/a*********************************************** 


*  * 

*  CP/M  BDOS-  AND  BIOS-  CALLS  FOR  C/80  * 

*  * 

t  Contributed  by  T.  Bolstad,  ELEKTROKQNSULT  AS  ♦ 

%  Konnerudgaten.  3,  N— 3000  Drammen,  NORWAY.  * 

*  * 

*  Date:  January  17,  1983.  * 

*  * 


*************************************************/ 


/*  DEFINITION  OF  BDOS  FUNCTIONS  */ 


ttdef i ne 

RESET 

0 

/* 

ttde-f  i  ne 

CONS IN 

1 

/* 

ttdef i ne 

CONSOUT 

2 

/* 

ttdef i ne 

READ IN 

3 

/* 

ttde-f  i  ne 

PUNOUT 

4 

/% 

ttde-f  i  ne 

LI STOUT 

5 

/* 

ttde-f  i  ne 

DIRCON 

6 

/* 

ttde-f  i  ne 

GET I OB 

7 

/* 

ttde-f  i  ne 

SET I OB 

8 

/* 

ttde-f  i  ne 

PRNTST 

9 

/* 

ttdef i ne 

READCB 

10 

/* 

ttdef i ne 

GETCST 

11 

/* 

ttde-f  i  ne 

RETVN 

12 

/* 

ttde-f  i  ne 

RESDSK 

13 

/* 

ttde-f  i  ne 

SELDISK 

14 

/* 

ttde-f  i  ne 

OPENF 

1 5 

/* 

ttdef i ne 

CLOSEF 

16 

/* 

ttde-f  i  ne 

SRCHFF 

17 

/* 

ttdef ine 

SRCHFN 

18 

/* 

ttde-f  i  ne 

DELF 

19 

/* 

ttdef i ne 

RDSEQ 

20 

/* 

ttdef i ne 

WRSEQ 

21 

/* 

ttdef i ne 

MAKEF 

22 

/* 

ttdef i ne 

RENF 

23 

/* 

ttdef i ne 

RETLV 

24 

/* 

ttdef i ne 

RETCD 

25 

/* 

ttdef i ne 

STDMA 

26 

/* 

ttdef i ne 

GET  A  A 

27 

/* 

ttdef i ne 

WPDSK 

28 

/* 

ttdef i ne 

GETROV 

29 

/* 

ttdef i ne 

SETFAT 

30 

/% 

SYSTEM  RESET  */ 
CONSOLE  INPUT  */ 
CONSOLE  OUTPUT  * / 
READER  INPUT  */ 
PUNCH  OUTPUT  */ 
LIST  OUTPUT  #/ 
DIRECT  CONSOLE  I/O  */ 
GET  I/O  BYTE  */ 
SET  I/O  BYTE  */ 
PRINT  STRING  */ 
READ  CONSOLE  BUFFER  */ 
GET  CONSOLE  STATUS  */ 
RETURN  VERSION  NUMBER  #/ 
RESET  DISK  SYSTEM  */ 
SELECT  DISK  */ 
OPEN  FILE  */ 
CLOSE  FILE  */ 
SEARCH  FOR  FIRST  */ 
SEARCH  FOR  NEXT  */ 
DELETE  FILE  */ 
READ  SEQUENTIAL  */ 
WRITE  SEQUENTIAL  */ 
MAKE  FILE  */ 
RENAME  FILE  */ 
RETURN  LOGIN  VECTOR  */ 
RETURN  CURRENT  DISK  */ 
SET  DMA  ADDRESS  */ 
GET  ALLOCATION  ADDRESS  */ 
WRITE  PROTECT  DISK  */ 
GET  READ/ONLY  VECTOR  */ 
SET  FILE  ATTRIBUTES  */ 
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#def i ne 

GETDPA 

31 

/* 

GET  DISK  PARAMETERS  ADDRESS 

*/ 

#de-f i ne 

SGUC 

32 

/* 

SET/GET  USER  CODE 

%/ 

#def i ne 

RDRAN 

33 

/* 

READ  RANDOM 

%/ 

#def i ne 

WRRAN 

34 

/* 

WRITE  RANDOM 

%/ 

#def i ne 

COMFS 

35 

/* 

COMPUTE  FILE  SIZE 

*/ 

#def i ne 

SETRRC 

36 

/% 

SET  RANDOM  RECORD 

%/ 

ttde-f  i  ne 

RESDRV 

37 

/* 

RESET  DRIVE 

%/ 

#def i ne 

WRRZF 

38 

/% 

WRITE  RANDOM  WITH 

ZERO  FILL 

*/ 

bdos (f unct , arg)  /*  corresponds  to  bdos ( (BC) , (DE) )  %/ 

int  f unct, arg; 


/*  CALL  EXAMPLE:  bdos (RETVN, 0) 

BOTH  ARGUMENTS  MUST  BE  SPECIFIED  ! 

Values  are  returned  IN  HL.  BDOS  errors 

are  returned  as  —1.  %/ 


#asm 

CPBASE 

EQU 

O 

; NORMAL  O-ORG’ED  CP/M 

CPNTRY 

E0U 

CPBASE+5 

; BDOS  ENTRY 

POP 

H 

; GET  RETURN  ADDRESS 

POP 

D 

; GET  ARG  (INFORMATION  ADDRESS) 

POP 

B 

; GET  FUNCTION  NO. 

PUSH 

B 

; RESTORE  STACK 

PUSH 

D 

PUSH 

H 

PUSH 

B 

; SAVE  FUNCTION  NO.  ON  STACK 

CALL 

CPNTRY 

; BDOS  CALL 

XCHG 

; SAVE  HL  IN  DE 

MOV 

L,  A 

; SAVE  A  IN  L 

; SIGN  EXTENSION  TO  H: 

RLC 

;  GET  SIGN  BIT  INTO  CY 

SBB 

A 

;  IF  CY=0,  RESULT  AFTER  SBB  IS  ZERO 

;  IF  CY=1,  RESULT  AFTER  SBB  IS  -1  (IE  ALL  ONES) 

MOV 

H,  A 

;  NOW  A  IS  MOVED  TO  HL  WITH  SIGN  EXTENSION 

POP 

B 

; GET  FUNCTION  NO  IN  BC 

MOV 

A,  C 

; GET  FUNCTION  NO  IN  A 

CPI 

12 

; WAS  IT  ' RETURN  VERSION  NUMBER ’  ? 

JZ 

RETHL1 

CPI 

24 

; RETURN  LOGIN  VECTOR  2 

JZ 

RETHL1 

CPI 

27 

; GET  ALLOCATION  ADDRESS  ? 

JZ 

RETHL1 

CPI 

29 

; GET  READ/ONLY  VECTOR  ? 

JZ 

RETHL1 

CPI 

31 

; GET  DISK  PARAMETER  ADDRESS? 

JZ 

RETHL1 

JMF 

BDOSRET 

(Continued  on  next  page) 
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BDOS  and  BIOS  Calls  for  C 

Listing  One  (Listing  continued,  text  begins  on  page  22) 


RETHL1 :  XCHG 

BDOSRET :  RET  ;WITH  RETURNED  VALUE  IN  HL 

#endasm 


/*  DEFINITION  OF  BIOS  FUNCTIONS  %/ 


#def i ne 

BOOT 

o 

/* 

COLD-BOOT 

*/ 

#def i ne 

WBOOT 

1 

/% 

WARM-BOOT 

*/ 

#def i ne 

CONST 

2 

/% 

CONSOLE  STATUS 

*/ 

#def i ne 

CON  IN 

3 

/% 

CONSOLE  INPUT 

*/ 

#def i ne 

CONOUT 

4 

/* 

CONSOLE  OUTPUT 

*/ 

#def i ne 

LIST 

5 

/% 

LIST  DEVICE 

*/ 

#def i ne 

PUNCH 

6 

/% 

PUNCH 

*/ 

ttdef  i  ne 

READER 

7 

/* 

READER 

*/ 

#def i ne 

HOME 

8 

/% 

HOME  DISK  DRIVE  HEAD 

%/ 

#def i ne 

SELDSK 

9 

/% 

SELECT  DISK  DRIVE 

*/ 

#def i ne 

SETTRK 

io 

/% 

SET  TRACK 

*/ 

#def i ne 

SETSEC 

1 1 

/% 

SET  SECTOR 

%/ 

#def i ne 

SETDMA 

12 

/% 

SET  DMA  ADDRESS 

%/ 

#def i ne 

READ 

13 

/* 

READ  ONE  SECTOR 

%/ 

#def i ne 

WRITE 

14 

/* 

WRITE  ONE  SECTOR 

%/ 

ttdef i ne 

LISTST 

15 

/% 

LIST  STATUS 

%/ 

#def i ne 

SECTRAN 

16 

/% 

SECTOR  TRANSLATION 

%/ 

bi os (f unct , arg 1 , arg2)  /*  corresponds  to  bios (function, (BC) , (DE) )  */ 

int  tunct,argl,arg2; 

/*  CALL  EXAMPLE:  bi os (SETTRK, 5, O) 

ALL  3  ARGUMENTS  MUST  BE  SPECIFIED,  even  though 
the  last  one  is  only  used  by  SELDSK  and  SECTRAN.  #/ 

C 

#asm 


POP 

D 

; RETURN  ADDRESS 

POP 

H 

; ARGUMENT  2 

SHLD 

ARG2S 

; SAVE  IT 

POP 

B 

; ARGUMENT  1 

XCHG 

; GET  RETURN  ADDRESS  INTO  HL 

POP 

D 

; FUNCTION  NO. 

PUSH 

D 

; RESTORE  SP 

PUSH 

B 

PUSH 

B 

PUSH 

H 

; RESTORE  RETURN  ADDRESS 

PUSH 

D 

; SAVE  FUNCTION  NO.  ON  STACK 

LX  I 

H,  O 

; CALCULATE  OFFSET  ADDRESS  FROM  FUNCTION 

DAD 

D 

;  GET  FUNCTION  NO.  (OFFSET)  IN  HL 
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DAD 

DAD 

XCH6 


H 

D 


2*OFFSET 

3*OFFSET 

SAVE  OFFSET  ADDRESS  IN  DE 


LHLD 

CFBASE+1 

; GET  POINTER  TO  BIOS  WBOOT  ENTRY 

DCX 

H 

; DECREMENT  TO 

DCX 

H 

;  POINT  TO 

DCX 

H 

;  START  OF  BIOS  ENTRY  JUMP  TABLE 

DAD 

D 

; ADD  OFFSET  (RESULT  IN  HL) 

XCHG 

; GET  RESULT  IN  DE 

LX  I 

H, RET  1 

PUSH 

H 

; SAVE  RETURN  ADDRESS  ON  STACK 

LHLD 

ARG2S 

; GET  ARGUMENT  2 

XCHG 

; GET  ARGUMENT  2  INTO  DE 

;  AND  BIOS  FUNCTION  ENTRY  ADDRESS  INTO 

PCHL 

; GO  TO  BIOS 

RET 1 :  XCHG  ;  SAVE  HL  IN  DE 

MOV  L, A 

RLC 

SEE  A 

MOV  H, A 

POP  B 

MOV  A, C 

CPI  9 

JZ  RETHL2 

CPI  16 

JZ  RETHL2 

JMP  RETBIOS 

RETHL2:  XCHG  ; RETURN  VALUE  IN  HL 

RETBIOS:  RET 
ARG2S:  DS  2 

#endasm 

J  End  Listing  One 


Listing  Two 

ttinclude  "cpmcall.c" 
mai n ( ) 

C 

bios (CONOUT, bdos (RETCD, O) +  A’ , O) ;  /%  print  current  disk  %/ 

> 


End  Listing  Two 


; GET  SIGN  BIT  INTO  CY 

; IF  CY=0,  RESULT  AFTER  SUBB  IS  ZERO 
; IF  CY=1 ,  RESULT  AFTER  SUBB  IS  -1  (IE  ALL  ONES) 

; GET  BIOS  FUNCTION  NO.  IN  BC 

; SELECT  DISK  FUNCTION  ? 

; SECTOR  TRANSLATION  FUNCTION  ? 
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Printing  Graphics 
Using  the  IBM  PC 


The  combination  of  the  Color/Graph¬ 
ics  Adapter  and  a  printer  capable  of 
“dot  graphics”  provides  a  powerful 
utility  function.  The  figure  on  page  36 
shows  an  example  of  the  image  produced. 
PC-DOS  at  levels  v.1.0  and  v.1.1  does  not 
provide  direct  support  for  this  function. 
As  this  article  is  being  written,  v.2.0  was 
announced.  I’ve  heard  that  the  new  re¬ 
lease  corrects  this  omission,  but  my  local 
suppliers  can’t  supply  v.2.0  as  yet,  so  I’ll 
ignore  this  new  capability.  All  references 
to  PC-DOS  in  this  article  should  be 
assumed  to  refer  to  v.1.0  or  v.1.1. 

I’ve  attempted  to  keep  this  at  a 
“general”  level,  so  that  those  of  you  who 
have  “different”  hardware  may  use  the 
information  to  write  your  own  utility. 
Specifically,  however,  the  article  (and 
included  listing)  is  written  for  the  stan¬ 
dard  IBM  Color/Graphics  Adapter  and  the 
original  IBM  Printer  (EPSON  MX-80) 
with  the  GRAFTRAX  PLUS  ROM  in¬ 
stalled!  As  I’m  sure  many  of  you  are 
aware,  the  MX-80  produces  quite  variable 
results  depending  upon  which  control 
ROM  is  installed.  The  Graphics  printer, 
provided  on  later  models,  should  also 
work  “as  is,”  but  minor  adjustments 
may  be  required. 

To  introduce  the  “solution,”  it  is  first 
necessary  to  define  the  problem.  In  its 
simplest  form,  the  problem  is  that  of 
mapping.  The  color/graphics  regeneration 
buffer  contains  a  bit-encoded  form  of  the 
displayed  image.  Dot  matrix  printers  also 
use  a  bit-encoded  form  of  the  image  to 
be  printed.  As  you  might  expect,  the  two 
encoded  forms  are  not  even  similar.  The 
requirement  for  this  utility,  then,  is  simply 
that  of  mapping  one  bit-encoded  form  to 
another.  Of  course,  before  mapping  can 
be  performed,  it  is  first  necessary  to 
understand  the  “rules”  for  encoding  in 
bo^i  the  input  and  output  forms. 


by  Dan  Daetwyler 


Dan  Daetwyler,  Route  5,  Box  518A, 
Springdale,  Arkansas  72764. 

References  are  made  to  IBM-PC,  PC- 
DOS,  etc.,  which  are  registered  trademarks 
of  International  Business  Machines  Cor¬ 
poration,  Armonk,  N.Y.,  and  to  EPSON 
MX-80,  GRAFTRAX  PLUS,  etc.,  which 
are  registered  trademarks  of  Epson 
America,  Inc. 


Display  Regeneration  Buffer  Format 

For  detailed  specification  of  the 
input  form,  you  are  referred  to  the  IBM 
Technical  Reference  Manual  for  the  PC. 
This  article  considers  only  the  medium- 
resolution  graphic  mode,  and  includes  the 
basic  information  that  describes  the  bit 
stream  used  in  this  mode.  In  this  mode 
the  addressable  unit  is  the  “pel,”  and  the 
screen  image  is  composed  of  64,000  pels. 
The  pels  are  “compressed”  so  that  each 
byte  of  the  buffer  contains  four  pels, 
hence  the  regeneration  buffer  size  is 
16,000  bytes.  Due  to  the  compression, 
each  pel  must  be  two  bits  in  size,  giving 
four  possible  bit  patterns  (0  through  3). 
The  zero  pattern  indicates  the  “back¬ 
ground”  color,  while  patterns  1  through  3 
indicate  which  of  the  three  possible 
“foreground”  colors  has  been  selected. 
Palette  selection  and  background  color 
selection  are  not  germane  to  this  article, 
so  I’ll  ignore  them. 

So  far,  this  encode  seems  simple.  You 
need  only  visualize  a  string  of  bytes  which 
are  associated  with  the  screen  positions. 
The  first  byte  of  the  buffer  is  the  upper 
left  corner  of  the  screen.  The  four  pels 
corresponding  to  the  first  four  dots  (left 
to  right)  at  the  upper  left  corner  of  the 
screen  are  in  this  byte.  The  second  byte 
contains  the  next  four  dots,  etc.,  until 
320  dots  have  been  defined  (80  bytes). 
Unfortunately,  this  simple  and  straight¬ 
forward  representation  now  breaks  down. 
The  second  row  of  dots  on  the  screen  is 
not  the  next  80  bytes  of  the  buffer,  but 
rather  is  the  80  bytes  at  an  offset  of  8000 
in  the  buffer.  The  regeneration  buffer  is 
organized  into  two  blocks  or  banks  of 
8000  bytes  each.  I  won’t  bore  you  with 
the  rationale  behind  this  organization, 
since  it’s  purely  related  to  hardware  design 
and  addressing.  From  our  viewpoint  it’s 
sufficient  to  know  that  even-numbered 
rows  are  stored  in  the  first  bank,  while 
odd-numbered  rows  are  in  the  second 
bank. 

To  summarize,  medium-resolution 
graphic  images  appear  in  the  regeneration 
buffer  as  they  appear  on  the  screen,  left 
to  right,  top  to  bottom,  but  the  pels  are 
compressed  four  to  a  byte,  and  alternate 
rows  are  stored  in  alternate  banks. 

Print  Line  Buffer  Format 

Dot  matrix  printing,  on  the  other 
hand,  considers  a  print  “line”  to  contain 
eight  rows  of  dots,  left  to  right,  top  to 
bottom.  The  most  significant  bit  of  each 
byte  corresponds  to  the  top  row  of  dots 


in  the  print  line.  The  printer  used  for  the 
program  provided  offers  two  forms  of  dot 
matrix  print:  normal  and  high  density. 
High  density  gives  maximum  resolution, 
so  that  was  chosen.  When  operating  in 
dot  matrix,  high-density  mode,  the  printer 
will  record  960  columns  in  the  maximum 
print  line  (a  column  is  a  “dot”).  Although 
one  could  map  the  graphic  screen  on  a 
pel-to-dot  basis,  the  image  would  be 
small,  and  no  simulation  of  color  would 
be  possible.  Since  the  maximum  screen 
line  contains  320  pels,  dividing  960  by 
320  gives  us  three  dots  per  pel  available. 
A  little  experimentation  or  computation 
shows  that  using  a  vertical  dimension  of 
two  gives  an  image  result  that  approxi¬ 
mates  screen  proportion.  Our  mapping 
function,  then,  will  map  a  pel  to  a  3x2 
dot  matrix.  This  also  permits  control  of 
the  dot  density  in  this  matrix  to  simulate 
color.  Mapping  for  100%  density  gives  a 
very  dark  pel,  while  mapping  for  30% 
density  gives  a  light  pel. 

Now  we  can  rough  out  the  mapping 
function  required.  It  must  select  pels  from 
the  regen  buffer,  by  unpacking.  These 
pels  must  be  mapped  to  the  corresponding 
3x2  position  in  the  printer  buffer  (left  to 
right).  The  mapping  function  must  also 
determine  the  row  number  of  the  pel  and 
select  from  either  the  first  bank  of  the 
buffer  for  even-numbered  rows  or  the 
second  bank  for  odd-numbered  rows. 


Program  Description 

Having  determined  the  method  of 
mapping,  let’s  look  at  one  program  (see 
listing  on  page  38)  that  uses  this  scheme. 
PRTGRPH  is  a  small,  totally  self-contained 
utility  that  will  perform  this  mapping.  It 
is  written  to  produce  a  “.COM”  file,  since 
such  a  file  is  easier  to  patch  if  a  change  in 
control  streams  is  required.  The  constants 
and  data  areas  are  given  at  the  start  of  the 
program,  but  we’ll  skip  over  all  of  them 
initially. 

The  program  proper  starts  with  the 
control  procedure,  PRTGRPH.  Initializa¬ 
tion  consists  of  setting  the  extra  segment 
register  to  the  segment  address  of  the 
regen  buffer  (0B800H),  and  using  stan¬ 
dard  DOS  functions  to  prompt  for  (and 
accept)  a  title.  The  title  is  then  “termi¬ 
nated”  by  a  “  $  ”  and  left  in  the  title  save 
area,  LBUF,  for  later  use.  The  printer  is 
initialized  by  output  of  the  control 
stream,  LSPC.  For  the  standard  GRAF- 


32 

298 


Dr.  Dobb’s  Journal,  Number  80,  June  1983 


TRAX  PLUS  ROM,  the  printer  control 
string: 

Escape,  A,  8 

sets  the  printer  to  a  line  height  of  8/72 
inches.  If  you’re  using  a  different  ROM, 
this  control  stream  must  be  modified  to 
match  your  ROM.  A  little  experimentation 
using  DEBUG  to  modify  the  control  string 
should  allow  you  to  determine  the  proper 
line  spacing  for  your  printer. 

Initialization  is  completed  by  setting 
the  line  count  register  (CX)  to  50  (twice 
the  lines  on  the  screen),  and  the  regen 
buffer  register  to  a  zero  offset  (SI).  The 
main  process  loop  at  GRP  1  is  then  entered. 
The  call  to  PUTLNE  will  cause  one  print 
line  to  be  generated  and  printed.  The  buf¬ 
fer  register  is  stepped  to  the  offset  (start) 
of  the  next  four  display  lines  to  be  printed, 
and  the  process  loops  when  the  line  count 
is  zero.  The  remainder  of  the  code  in 
PRTGRPH  simply  restores  the  printer  to 
normal  spacing  and  mode,  prints  the 
saved  title,  and  restores  the  printer  page 
to  the  start  of  the  next  page. 

The  next  procedure,  PUTPRT,  simply 
puts  a  string  (terminated  by  a  “$”)  to 
the  printer.  The  code  makes  the  function 
obvious,  and  I  won’t  waste  space  describ¬ 
ing  this  procedure. 

PUTLINE  clears  the  print  buffer, 
builds  the  dot  image,  and  then  prints  it. 
It’s  called  once  per  line  and  is  inserted  in 
the  program  flow  to  preserve  the  entry 
values  of  the  line  counter  and  the  regen 
buffer  register.  Useful  work  is  performed 
by  CLRBUF,  BLDLNE,  and  PRTLNE 
which  are  called  by  this  procedure. 

CLRBUF  again  is  a  straightforward 
routine  that  simply  pre-sets  the  printer 
buffer  to  binary  zeros.  PRTLNE  simply 
prints  the  buffer,  but  in  this  case,  it 
initializes  the  printer  for  dot  matrix  print¬ 
ing.  This  is  done  by  output  of  the  string 
BGRPH,  which  for  the  utilized  ROM  is: 

Escape,  L,  192,  3 

This  cryptic  string  tells  the  printer  to 
enter  high-density  (“L”)  print  mode  for 
a  line  length  of  192  +  (3  *  256),  or  960 
dots.  This  re-initialization  is  required  for 
each  line,  since  the  printer  simply  enters 
and  stays  in  dot  matrix  mode  for  the  byte 
count  defined  by  this  line  length.  It  then 
returns  to  the  mode  it  was  in  when  it 
started  the  process. 

BLDLNE  is  the  basic  mapping  func¬ 
tion.  It  begins  by  setting  the  print  buffer 
register  (DI)  to  zero,  and  an  internal  loop 
counter  (BX)  to  the  number  of  bytes  in 
the  line  (80).  A  two-bit  mask  (0C0H)  is 
set  in  the  DH  register,  and  the  inner  loop 
counter  (CH  is  set  in  the  outer  loop, 
OLP.  The  inner  loop,  ILP,  begins  by  clear¬ 
ing  the  shift  count  (CL)  and  loading  the 
first  regen  byte  for  this  print  line  into  the 
AL  register.  This  byte  is  masked  by  the 
content  of  DH  and  the  result  tested  for 
zero.  If  zero,  this  pel  is  background  color 


and  is  skipped.  If  non-zero,  the  call  to 
SAVPEL  is  executed.  In  either  case,  the 
logic  flow  picks  up  at  PEL2  which  steps 
the  shift  count  by  2  and  loads  the  next 
regen  data  byte. 

SAVPEL,  which  will  be  discussed  in 
more  detail  later,  simply  fills  in  the  3x2 
matrix  with  a  dot  pattern  suitable  for  the 
color  code  determined  by  this  masking 
process.  Since  the  print  line  image  is 
being  built  a  pel  at  a  time,  left  to  right, 
the  code  at  PEL2,  PEL3,  and  PEL4  loads 
data  from  the  appropriate  bank  of  the 
regen  buffer,  and  at  the  appropriate  off¬ 
set.  Consider  the  first  use  of  the  routine. 
The  SI  register  contains  zero  on  entry,  so 
the  regen  data  load  at  ILP  is  of  the  first 
byte  of  the  regen  buffer,  which  corre¬ 
sponds  to  the  first  three  dots  in  the  first 
two  rows  of  the  print  line  (3x2  matrix 
again).  The  load  at  PEL2  is  for  the  second 
two  rows  of  the  dot  matrix  print  line, 
which  correspond  to  the  second  row,  first 
byte  of  the  displayed  image.  It  therefore 
is  an  odd-numbered  row  and  must  load 
from  the  second  bank  of  the  regen  buffer 
(SI+2000H).  The  load  at  PEL3  is  back  to 
an  even-numbered  row,  but  it  is  now  the 
third  row  of  the  displayed  image  (row  2 
when  considering  zero  as  the  first  row), 
and  must  load  from  the  first  bank,  second 
line,  or  offset  5  OH  (80  characters  into 
the  buffer).  The  load  at  PEL4  follows 
the  same  logic,  but  it  is  again  an  odd- 
numbered  row  so  the  loading  offset  is 
2050H. 

Reaching  STP,  the  code  has  completed 
the  first  three  columns  of  the  print  line 
(eight  rows),  so  the  print  buffer  register 
is  stepped  by  three.  The  mask  is  shifted 
to  the  next  pel  position,  and  the  inner 
loop  count  decremented.  This  inner  loop 
will  execute  four  times  (for  the  four  pels 
in  the  screen  byte),  and  then  exit  to  a 
step  of  the  regen  buffer  register,  moving 
to  the  next  four  pels.  The  outer  loop 
counter  (BX  is  decremented,  and  the 
process  continues  until  80  regen  buffer 
bytes  have  been  processed.  This  corre¬ 
sponds  to  one  display  line,  and  the  build 
function  exits. 

To  complete  the  code  description, 
SAVPEL  simply  converts  the  color  code 
masked  from  the  pel  to  a  dot  matrix  code 
of  suitable  density  and  stores  this  code  in 
the  print  line  buffer.  You’ll  note  that  the 
mask  saved  in  the  print  line  buffer  is  saved 
in  a  two-bit  space  (the  two  part  of  the 
3x2  matrix)  and  is  saved  in  three  bytes 
(the  three  part).  Since  we  don’t  know  in 
which  two-bit  field  the  pel  is  located  in 
this  procedure,  the  test  checks  all  four 
two-bit  fields.  It  checks  first  for  the  pres¬ 
ence  of  a  “one  bit”  in  the  two-bit  fields. 
If  not  found,  it  assumes  that  the  color 
code  is  a  two,  since  the  routine  would 
not  be  entered  if  the  color  code  is  zero. 
If  a  one  bit  is  found,  then  a  two  bit  is 
checked.  If  not  found,  the  color  code  is 


one,  while  if  found,  the  color  code  is 
three.  The  DL  mask  and  the  CL  shift  may 
be  modified  to  give  different  shade  pat¬ 
terns.  The  one  provided  in  the  code  seems 
to  give  a  good  contrast  between  colors, 
yet  provides  a  pleasing  overall  density. 
You  can  try  other  combinations  and 
select  the  one  most  suited  to  your  printer 
(and  your  eye). 

That’s  it.  The  listing  is  relatively  well 
commented,  so  try  reading  through  the 
code  if  this  description  doesn’t  seem  clear. 

Assembly  and  Link 

Key  in  the  source  code  as  shown  in 
the  listing,  and  assemble  using  either  of 
the  assemblers.  If  you  have  a  different 
printer  or  control  ROM,  you  should 
change  the  printer  control  strings  to 
match  your  configuration.  Link  as  you 
would  any  other  program.  The  link  will 
respond  with  a  “warning”  message  inform¬ 
ing  you  that  there  is  no  stack  segment 
and  will  give  an  error  count  of  one.  Ig¬ 
nore  this  error  message  and  execute 
EXE2BIN.  Rename  the  resultant  file 
“name.COM”  and  execute. 

For  those  of  you  who  are  operating 
at  PC-DOS  v.1.0,  you  may  not  have  the 
DOS  utility  EXE2BIN,  which  is  almost 
necessary  to  produce  a  “.COM”  file.  You 

may,  therefore,  prefer  an  “.EXE”  file.  If 
so,  you  must  add  a  stack  segment,  initial¬ 
ize  your  data  segment  register,  initialize 
the  stack  for  the  eventual  return  to  DOS, 
and  change  the  PRTGRPH  procedure  to  a 
“FAR.” 

Use  of  the  Utility 

Use  of  the  utility  is  primitive,  with 
one  big  “hooker.”  The  utility  will  print 
the  content  of  the  color/graphics  regenera¬ 
tion  buffer,  at  the  instant  of  execution. 
How  you  invoke  this  utility  without  dis¬ 
turbing  this  buffer  is  a  function  of  how 
you’re  configured.  I’m  working  with  both 
the  monochrome  and  the  color/display 
adapters,  so  it’s  easy  for  me.  I  simply 
arrange  my  graphics  program  so  that  it 
does  not  clear  the  graphics  screen  on  exit, 
and  switches  back  to  the  monochrome 
display  before  exit.  That  leaves  the  graph¬ 
ics  regen  buffer  containing  the  image  I 
want,  and  I  can  enter  the  command  to 
execute  this  utility  on  the  monochrome 
display.  If  you  have  only  the  color/graphics 
adapter,  you’ll  have  to  be  considerably 
more  complex  in  your  process.  One  trick 
is  to  include  code  in  your  display  genera¬ 
tion  program  that  writes  the  entire  regen 
buffer  to  disk  under  some  condition.  This 
utility  can  then  be  simply  modified  to 
load  the  buffer  image  into  memory  and 
point  to  it  instead  of  the  regen  buffer. 

Finally,  this  program  is  hereby  placed 
in  public  domain.  You  may  copy  it,  util¬ 
ize  it  in  your  own  work,  etc.  freely  and 
without  notification. 
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Although  this  utility  is  small  and  not 
too  much  keying  is  required,  I  will  pro¬ 
vide  copy  service.  A  single -surface  disk¬ 
ette  and  a  check  for  $5  will  get  you  a 
copy  of  the  program  source  materials, 
object  file,  and  an  executable  “.COM” 
file.  A  check  for  $7.50  will  get  you  a  new 
Verbatim  (or  equivalent)  containing  the 
same  materials.  I’ll  furnish  the  return 
mailer  and  will  ship  UPS  Blue  Label 
unless  otherwise  instructed.  Send  to:  Dan 
Daetwyler,  Route  5,  Box  5 18 A,  Spring- 
dale,  AR  72764  (that’s  Arkansas,  not 
Arizona). 

If  you  have  trouble/questions  with 
this  one,  you  can  write  me  at  the  above 
address,  or  call  501-756-0212.  (I’m  usu¬ 
ally  around  24  hours,  seven  days.)  Good 
luck  and  happy  printing. 

»»J 


(Listing  begins  on  page  38) 


SSsshk 


WjWS'iSwctXo 


mmmm 

■■■ 


Ml 


ViYijYi 


WSwSa 
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Printing  Graphics  on  the  IBM  PC  (Text  begins  on  page  32) 


COMMENT  \ 

*********  #**#»****#***#******##)(#******###*##***♦***#**###**#***#*********#**'* * 

*  Copyright  1983  -  DD  Systems  -  Springdale,  AR  * 

******************************************************************************* 

*  * 

*  Output  Color  Graphic  Screen  to  Printer  * 

*  * 

*  This  self-contained  utility  maps  the  "pel"  maps  of  the  color  graphic  * 

*  refresh  buffer  to  the  printer.  It  assumes  the  image  has  been  * 

*  loaded  by  other  services.  * 


****************************************************************************** \ 


CODE 

SEGMENT 

PARA  PUBLIC  "CODE'' 

ASSUME 

CS: CODE, DS: CODE 

ORG 

1 OOH 

BEGIN: 

JMP 

PRTGRPH 

PRMPT 

DB 

’Enter  Title:  $’ 

LSF'C 

DB 

27,  ’A’  , 8,  13,  10, ’ $’ 

BGRPH 

DB 

27, ’L’ , 192,3, 

NORM 

DB 

27, 

CRLF 

DB 

13, 10, ’ 

% 

LB  1JF 

DB 

80 

DB 

82  DUP  (?) 

PBUF 

DB 

960  DUP  ( ? ) 

DB 

’S’ 

5 

PRTGRPH 

PROC 

NEAR 

MOV 

AX , 0B800H 

MOV 

ES,  AX 

MOV 

DX, OFFSET  PRMPT 

MOV 

AH,  9 

I  NT 

21H 

MOV 

DX, OFFSET  LBUF 

MOV 

AH,  10 

I  NT 

21 H 

MOV 

AL, LBUF+1 

CBW 

MOV 

SI,  AX 

MOV 

LBIJF+2ESI  3 , 

MOV 

SI,  OFFSET  L.SPC 

CALL 

PUTPRT 

MOV 

CX,  50 

MOV 

S 1 , 0 

GRP  1  : 

CALL 

PUTLNE 

ADD 

SI, 160 

LOOP 

GRP  1 

MOV 

SI, OFFSET  NORM 

CALL 

PUTPRT 

MOV 

SI, OFFSET  CRLF 

CALL 

PUTPRT 

MOV 

SI, OFFSET  LBUF +2 

CALL 

PUTPRT 

MOV 

CX,  31 

GRP2 : 

MOV 

SI, OFFSET  CRLF 

CALL 

PUTPRT 

LOOP 

GRP2 

MOV 

SI, OFFSET  NORM 

CALL 

PUTPRT 

RET 


; Pr omp t  for  title  line 
(Sets  printer  to  8/72"  spacing 
;Sets  t.o  hi -density  dot  graphics 
; Resets  to  normal  mode 


5  Title  buffer 
5  B i t  graphics  buf  fer 


5  Addressabi  .1  i  ty  of  regen  buffer 


5  Prompt  for  caption 


;  Get.  title  1  i  ne 
; Get  entry  length 


!i  Set  line  terminator 

5  Set  printer 
j Print  line  count 
; Start  of  regen  buffer 
(Output  one  line 
5  which  is  four  screen  rows 


5  Restore  printer  to  normal 
; Space  line 
(Output  title 


5  Space  to  end  of  page 
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Printing  GrdphiCS  on  thG  IBM  PC  (Listing  continued,  text  begins  on  page  32) 

PRTGRPH  ENDP 


Simple  "put  string"  to  printer 


PUTPRT 

PROC 

NEAR 

PUSH 

SI 

PUSH 

DX 

PPL.P: 

MOV 

DL, BYTE  PTRCSII 

CMP 

DL, ’ 

5  Check  for  "end  of  string"  mark 

JZ 

PPDNE 

MOV 

AH  ,5 

INI 

21 H 

;D0S  Printer  call 

INC 

SI 

JMP 

PPLP 

PPDNE: 

POP 

DX 

POP 

SI 

RET 

PUTF'RT 

ENDP 

i 

i 

• 

Output 

one  graphic  "line" 

PUTLNE 

PROC 

NEAR 

PUSH 

SI 

PUSH 

CX 

CALL 

CLRBUF 

; Cl  ear  bit  buffer 

CALL 

BLDLNE 

5  Bui  Id  dot  image 

CALL 

PRTLNE 

; Output  line 

POP 

CX 

POP 

SI 

RET 

F'UTLNE 

ENDP 

> 

5 

; 

CLRBIJP 

Cl  ear 

line  buffer  to  null 

PROC 

NEAR 

XOR 

D I ,  D I 

MOV 

AX,  DI 

MOV 

CX, 400 

CBLP: 

MOV 

WORD  PTR  PBIJFCDI I ,  AX 

5  Cl  ears  line  buffer  to  null 

INC 

DI 

INC 

DI 

LOOP 

RET 

CBLP 

CLRBIJP 

ENDP 

jl 

PRTL-NE 

PROC 

NEAR 

MOV 

SI,  OFFSET  BGRF'H 

CALL 

PUTPRT 

; Set  printer  for  dot  graphic  line 

MOV 

SI,  OFFSET  PBIJF 

MOV 

CX, 960 

?  and  output  bit  stream 

PL  1 : 

MOV 

DL, BYTE  PTR  CSI3 

MOV 

AH,  5 

I  NT 

2 1 H 

INC 

SI 

LOOP 

RET 

PL.1 

PRTLNE 

ENDP 

Build 

dot  graphic  bit  stream 

in  buffer 

BLDLNE 

PROC 

NEAR 

XOR 

DI ,  DI 

; Dot  buffer  index 

MOV 

BX,  00 

5  Loop  count  for  line 

□LP : 

MOV 

DH, OCOH 

; Outer  loop  mask 

MOV 

CH,  4 

5  Inner  loop  counter 

xlp: 

XOR 

CL,  CL 

5  Shift  for  pel  save 
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MOV 

AL_ ,  BYTE  PTR  ES:CSI3  ;  Get  screen  byte 

AND 

AL, DH  j  Mask 

JZ 

PEL2 

CALL 

SAVPEL  jnon-zero,  so  print  blob 

PEL2: 

ADD 

CL,  2 

MOV 

AL, BYTE  PTR  ES: CSI+2000H1  5  Next  row 

AND 

AL ,  DH 

JZ 

F'EL3 

CALL 

SAVPEL 

PEL3: 

ADD 

CL,  2  ! Stepping  shift  count 

MOV 

AL, BYTE  PTR  ES: CSI+50H3  ; Row  three 

AND 

AL ,  DH 

JZ 

PEL  4 

CALL 

SAVPEL 

PEL4 : 

ADD 

CL,  2 

MOV 

AL, BYTE  PTR  ES: CSI+2050H3  5  Fourth  row 

AND 

AL ,  DH 

JZ 

STP 

CALL 

SAVPEL 

stp: 

ADD 

1)1,3  5  Step  save  buffer  pointer 

SHR 

DH,  1 

SHR 

DH, 1  5  Reposition  pel  mask 

DEC 

CH 

JNZ 

ILF'  ^Continue  inner  loop  for  next  col 

INC 

SI  5  Step  regen  buffer  ptr 

DEC 

BX 

JNZ 

OLP  ■;  Outer  loop 

RET 

BLDLNE 

ENDP 

a 

J 

Save 

bit  image  for  this  pel  -  different  "shade"  for  each  color 

SAVPEL 

PROC 

NEAR 

TEST 

AL,55H  ,One  bit.  on 

JNZ 

ONEB 

JMP 

DOTWO 

ONEB: 

TEST 

AL,0AAH  ;Test.  for  two  bit 

JNZ 

DOTHRE 

;  The 

•following  is  for  a  data  bit  of  01 

MOV 

DL,OCOH  ;Load  mask 

SHR 

DL.,CL  5  and  position 

OR 

PBUF ID I  3  ,  DL. 

OR 

PBUFCDI+1 3 , DL 

OR 

PBUF  t  D I +2  3 , DL 

RET 

DOTWO: 

MOV 

DL , 80H 

SHR 

DL,  CL 

OR 

PBUFCDI 3 , DL 

OR 

PBIJF  C  D I  +2  3  ,  DL. 

SHR 

DL,  1 

OR 

PBUFC  D 1  +  13,  DL 

RET 

DOTHRE: 

MOV 

DL , OCOH 

SHR 

DL,  CL 

OR 

PBUF  C  D I +2  3 , DL 

RET 

SAVPEL 

ENDP 

CODE 

ENDS 

END 

BEGIN 

End  Listing 
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The  Game  of  Life 

on  the  IBM-PC 


Computer  programs  for  running 
John  Conway’s  Game  of  Life  were 
quite  popular  a  few  years  ago.  The 
problem  with  these  older  simulations  was 
usually  their  speed:  a  single  generation  on 
a  ten-by-ten  grid  could  take  up  to  90  sec¬ 
onds.  Presented  here  is  a  version  of  the 
game  for  the  IBM/PC  computer.  Features 
of  this  version  are  adjustable  speed  (with 
2.7  generations/sec  as  a  top  speed),  easy 
entry  of  the  seed  generation  (via  a  screen- 
editor),  and  marking  of  cells  due  to  be 
“born,”  and  cells  remaining  alive  each 
generation  (as  different  from  cells  marked 
to  die).  This  feature  gives  a  better  impres¬ 
sion  of  fluidity  on  the  grid. 

This  version  requires  only  the  IBM 
monochrome  display  to  run,  and  will  run 
under  either  MS-DOS  or  CP/M-86,  since 
only  calls  to  the  IBM  ROM  are  made. 

Background 

The  Game  of  Life  takes  place  on  a 
square  grid.  Every  cell  on  the  grid  can  be 
either  alive  or  dead.  Every  cell  on  the  grid 
has  eight  neighbors.  Each  generation,  every 
cell  on  the  grid  is  evaluated.  The  cell  will 
remain  alive  if  it  has  two  or  three  neigh¬ 
bors,  or  will  die  if  it  has  less  than  two 
(from  loneliness),  or  more  than  three 
(from  overpopulation).  An  empty  cell 
will  have  a  “birth”  (a  live  cell  will  be 
placed  there  the  next  generation)  if  it  has 
exactly  three  neighbors.  The  game  was 
developed  by  John  Conway  in  1976. 

The  Program 

The  program  is  straightforward.  When 
first  run,  the  screen  is  cleared  and  the  cur¬ 
sor  is  positioned  in  the  center.  The  cursor 
may  be  moved  by  pressing  the  four  arrow 
keys  on  the  keyboard  (Num  Lock  doesn’t 
matter  because  the  keyscan  code  is  inter¬ 
rogated,  not  the  ASCII  code).  A  live  cell 
may  be  deposited  by  depressing  Ins,  and 
a  cell  may  be  cleared  by  pressing  Del. 
When  the  screen  is  complete,  pressing  Esc 
starts  evaluation  of  the  next  generation. 

The  program  stores  the  grid  in  the 
screen  memory  of  the  monochrome  dis¬ 
play.  Associated  with  every  displayable 
character  on  the  screen  are  two  bytes  of 
memory,  the  low  byte  for  the  character 
displayed,  and  the  hi  byte  for  the  display 
attributes  (underlined,  reversed,  etc.). 


by  Simson  L.  Garfinkel 


Simson  L.  Garfinkel,  18  Dartmouth  Lane, 
Haverford,  Pennsylvania  19041. 


The  program  uses  the  attribute  byte  of 
every  screen  position  as  a  second  array  to 
hold  the  next  generation  in  while  it  evalu¬ 
ates  the  present  generation. 

After  the  time  delay,  subroutine 
count  is  called.  Count  counts  the  number 
of  neighbors  that  every  ceil  has,  and  de¬ 
cides  whether  or  not  the  cell  will  be  alive 
in  the  next  generation.  If  it  is  going  to  be 
alive,  the  display  attribute  for  that  char¬ 
acter  is  set  to  rev.  If  the  cell  is  going  to  be 
dead,  the  attribute  is  set  to  dark.  Rev  and 
dark  are  reverse  video  and  normal  video 
in  my  listing,  so  when  a  cell  is  going  to 
have  a  birth  or  stay  alive,  it  is  inverted 
on  the  screen,  but  rev  and  dark  can  be 
changed  to  three  and  five,  causing  both  to 
display  as  normal  if  the  flickering  this 
produces  is  annoying. 

After  all  of  the  decisions  regarding 
life  and  death  are  made,  subroutine  update 
goes  through  screen  memory  putting  in 
the  character  for  a  live  cell  if  the  cell  is 
supposed  to  be  alive,  or  a  dead  cell  if  the 
cell  is  supposed  to  be  dead,  and  resetting 
the  attribute  byte. 

The  program  then  looks  for  a  user 
key  press.  If  one  has  occurred,  the  pro¬ 
gram  quits  if  it  was  an  Esc,  or  changes  the 
time  delay  value  if  it  was  a  digit.  Pressing 
0  gives  no  delay,  or  about  2.7  generations 
per  second.  Pressing  9  gives  a  3.5  second 
delay  per  generation. 

Expansions 

The  one  problem  with  this  imple¬ 
mentation  is  that  the  screen  doesn’t  have 
enough  rows  to  allow  a  simulation  of 
a  complex  colony.  I  would  love  to  see 
an  implementation  of  life  in  medium- 
resolution  color  graphics,  with  births  in 
blue  and  deaths  in  red,  but  I  don’t  have 
access  to  a  color  display,  so  that  will 
have  to  wait.  The  program  could  also  be 
cleaned  up  to  make  it  run  faster,  but  2.7 
generations  a  second  is  really  fast  enough 
for  most  applications. 

(Listing  begins  at  right) 
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Game  of  Life  (Text  begins  on  page  42) 


Comment  $ 

AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

*  A 

*  The  Game  of  Life  * 

A  A 

AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

John  Conway's  mathematical  game  of  life,  implemented  on 
the  IBM/PC,  fay  Simson  L.  Garfinkel. 

Written  in  8088  assembly  language  using  the  Microsoft 
Macro  Assembler. 

Notes  on  running  the  program: 

When  program  is  run: 

1.  Screen  clears. 

2.  User  enters  first  generation  from  keyboard. 

Arrow  keys  move  the  cursor.  INS  key  deposits 

a  live  cell,  DEL  removes  a  live  cell,  (in  case 
the  user  makes  a  mistake. ) 

3.  Pressing  ESC  starts  program. 

4.  For  each  generation,  cells  which  will  have  life 
on  the  neat  turn  are  inverted. 

5.  Screen  is  updated  to  next  generation. 

6.  Keyboard  is  interrogated  for  command. 

7.  If  ESC  is  pressed,  program  terminates. 

8.  If  a  number  0-9  is  pressed,  speed  is  selected. 

At  speed  0,  approx.  2.7  g e ne r a t i on s / s e c  are  performed 
At  speed  9,  each  generation  takes  3.5  sec. 

9.  program  loops  to  #4. 

$ 


;  global  definitions 


live 

equ 

02 

;  character  for 

a  live 

cell 

dead 

equ 

00 

jcharacter  for 

a  dead 

cell 

rev 

equ 

7  0  h 

;reverse  video 

(  ma  r  k  s 

cell 

t  o 

live) 

dark 

equ 

2 

; no  rma I  video 

(marks 

cell 

t  o 

die  ) 

t  i  me 

equ 

300 

; t i me  delay  base 

TERM 

equ 

2  7 

;Character  to 

exit  mo  d  e 

cseg  segment  para  public  1 codel 1 

start  proc  far 

assume  cs : cseg , ds : nothing , ss : stack , es : nothing 

; set  up  return  location 


(Continued  on  next  page) 
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Game  of  Life  (Listing  continued,  text  begins  on  page  42) 

push 

d  s 

sub 

a  x  ,  a  x 

push 

a  x 

;  now  I  can  go  home  when  I'm  finished 

call 

Enter 

i Enter  board 

mo  v 

cx  ,  0 

;initial  delay,  0 

mi  i  n  : 

push 

C  X 

; save  delay  variable 

cmp 

CX  ,  0 

j  * 

si  3 

s  1  : 

push 

C  X 

mo  v  c  k  ,  t  i  me 

s  1  1  : 

push  c  x 

mo  v  c  x , t i me 

s  1  2  : 

loop  s 1 2 

pop  C  X 

loop  s 1  1 

pop 

C  X 

loop 

s  1 

;what  a  time  delay! 

s  1  3  : 

call 

count 

iCount  up  every  cell's  neighbours, 

call 

update 

; Upda  te  screen 

pop 

c  X 

i  get  back  the  time  delay 

mo  v 

ah  ,  1 

;See  if  user  has  pushed  a  key 

i  n  t 

1  6h 

j  z 

roa  i  n 

;nope  -  loop  back 

mo  v 

ah  ,  0 

: get  the  character  our  of  the  buffer 

i  n  t 

1  6  h 

cmp 

a  1  ,  TERM 

j  nz 

s  2 

ret 

; f inished  -  go  back  to  ms/dos 

s  2  : 

cmp 

a  1  ,  1  0  ' 

;  see  if  it  is  a  speed  command 

i  b 

ma  i  n 

cmp 

a  1  ,  '  ?  1 

j  nb  e 

ma  i  n 

;  I  t  '  s  a  numb  e  r 

sub 

al,  'O' 

;  now  it  goes  from  0  to  9 

mo  v 

ah  ,  0 

mo  v 

c  x  ,  a  x 

; put  it  in  cx 

jmp 

ma  i  n 

start 

endp 

Enter 

proc 

ne  a  r 

;Subroutine  to  enter  board 
; def ine  scan-codes: 

left 

e  q  u 

75 

right 

e  q  u 

7  7 

up 

equ 

72 
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down 

equ 

80 

point 

equ 

82 

del 

equ 

83 

esc 

equ 

1 

call 

c  1  s 

;clear  the  screen 

;Registers  are 

used  as  foil ows : 

;  DH 

-  Y  position 

;  DL 

-  X  positi 

on 

mo  v 

dh  ,  1  2 

mo  v 

d  I  ,  4  0 

e  1  : 

mo  v 

bh  ,  0 

;move  the  cursor  to  x,y  position 

mo  v 

ah,  2 

;code  for  cursor  move 

i  n  t 

1  Oh 

; interrupt  for  cursor  move 

mo  v 

ah  ,  0 

i  set  up  to  read  the  next  keypress 

i  n  t 

1  6h 

; keypress  read 

cmp 

ah,  left 

;make  a  rational  decision  about  the  users 

j  z 

g  o_l eft 

;  entry  . 

cmp 

ah , right 

j  Z 

go_r i gh  t 

cmp 

ah  ,  up 

j  Z 

g  o_up 

cmp 

ah , down 

j  z 

g  o_d  own 

cmp 

ah, point 

j  Z 

go_po int 

cmp 

ah  ,  del 

j  Z 

g  o_d  e  1 

cmp 

ah , esc 

j  n  z 

e  1 

;  loop  back  -  unknown  command 

mo  v 

dx , 23*256 

;put  the  cursor  at  lower-left  hand  corner 

mo  v 

a  h  ,  2 

int 

1  Oh 

ret 

;  go  back  to  caller 

g  o_l eft: 

;  mo  ve  left  if  I  can 

cmp 

d  1  ,  0 

;  in  leftmost  collumn? 

i  z 

e  1 

;  yes  -  go  back 

sub 

d  1  ,  1 

;  no  -  subtract  one 

j  mp 

e  1 

;  g  o  back 

g  o_r i g  h  t 

;move  right  if  I  can. 

cmp 

d  1  ,  7  9 

j  Z 

e  1 

add 

d  I  ,  1 

j  mp 

e  1 

g  o_up  : 

;  go  up  i f  I  can 

cmp 

dh  ,  0 

j  Z 

e  1 

sub 

dh  ,  1 

imp 

e  1 

(Continued  on  next  page) 
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Game  of  Life  (Listing  continued,  text  begins  on  page  42) 


g  o_d  own : 

cmp 

dh  ,  2  4 

; go  down  if  I  can 

3  z 

e  1 

add 

dh  ,  1 

jmp 

e  1 

g  o_p o i n  t 

mo  v 

a  1  ,  1  i  v  e 

i put  a  live  dot  where  the  cursor 
jit's  the  live  character 

gp2  : 

mo  v 

c  x  ,  1 

;one  character  to  write 

mo  v 

ah  ,  1  0 

jcode  to  write  character 

i  n  t 

1  Oh 

;  d  o  it 

jmp 

e  1 

i  get  next  command 

g  o_d  e  I  : 

mo  v 

a  1  ,  d  e  a  d 

[delete  character  at  cursor 

jmp 

g  P  2 

i let  go_point  do  the  rest 

Enter 

endp 

C  1  s 

proc 

near 

jSubroutine  to  clear  the  screen 

mo  v 

a  x  ,  6  *  2  5  6 

mo  v 

c  x  ,  0 

mo  v 

dx,  24*256  +  79 

■-  don ' t  move  i t 


mo  v 
i  n  t 
ret 
endp 


bh  ,  2 
1  Oh 


Count  proc  near  ;Subrout ine  to  count  up  every  cell's  neighbours 

jRegisters  used: 

;DH,DL:  Y,X  of  current  cell  being  interrogated 

; DS  Base  offset  -  into  screen  memory 

;DI  offset  for  character  presently  being  looked  at 

; 

jOutline  for  each  character 
;  1 .  Count  up  number  of  neighbours 

;  2.  If  three  neighbours,  or  if  two  and  cell  is  live,  put 
;  a  rev  on  the  screen  at  the  attribute  position,  else 

;  putadark 

;  3.  Go  to  next  character 


ch  k 

ma  cro 

yy  ,  xx 

local 

chi  , o  f  f  s 

offs 

e  q  u 

( xx  +  yy*80  )  *2 

mo  v 

cx, Cdi+offsJ 

; g  e  t  byte 

to  check 

cmp 

cl , live 

; ch  e  c  k  to 

see  if  this  cell  is  al 

j  n  z 

chi 

;  no p e 

add 

a  1  ,  1 

i yes  -  increase  neighbour  count 

chi: 

endm 

(Continued  on  page  50) 
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mo  v 

ax , 0B000H 

mo  v 

d  s  ,  a  x 

;offset  value  for  monochrome  display 

mo  v 

dh  ,  1 

iStart  at  1,1  and  go  to  23,78 

mo  v 

d  1  ,  1 

; to  prevent  wrap-arround 

c  1  : 

mo  v 

ax,  160 

;get  true  offset  from  ds  into  screen  memory 

mu  1 

dh 

mo  v 

c  x  ,  d  x 

mo  v 

ch  ,  00 

;  just  get  dl 

add 

a  x  ,  c  h 

add 

a  x  ,  c  x 

;  ax : = ( dh*B0  +  dl  >  *2 

mo  v 

d  i  ,  a  x 

;  d  i  :  =  a  x 

mo  v 

a  x  ,  0 

;ax  will  be  used  for  neighbour  counting 

c  h  k 

-1,-1 

; count  number  of  neighbours 

chic 

-1  ,  0 

chic 

-  1  ,  +  1 

c  h  Ic 

0,-1 

chic 

0  ,  +  1 

c  h  k 

+  1,-1 

ch  k 

+  1  ,  0 

c  h  k 

+  1  /  +  1 

;  test  all  of  the  neighbours 

mo  v 

c  x  ,  C  d  i  ] 

;get  byte  to  check 

cmp 

a  1  ,  3 

j  z 

g  i  v  e_l i f  e 

;life  if  has  3  neighbours 

cmp 

cl , live 

;  is  it  alive? 

j  n  z 

g i v  e_d  e  a  t  h 

;  no 

cmp 

a  1  ,  2 

; he  lives  if  he  has  2  neighbours  and  he  is  already 

;  a  1  i  v  e 

j  n  z 

g i v  e_d  e  a  t  h 

;  no  p  e 

g  i  v  e__ 

life: 

;make  this  one  alive 

mo  v 

ch , rev 

imp 

c  2 

g  i  v  e  __ 

death  : 

mo  v 

c  h  ,  d  a  r  k 

c  2  : 

mo  v 

1  d  i  1  ,  c  x 

; put  back  on  the  screen 

ne  x  t_ 

cell  : 

cmp 

d  1  ,  78 

; am  I  at  the  end  of  the  X  line? 

j  z 

c  3 

;  y  e  s 

add 

d  I  ,  1 

;  no  p  e 

imp 

c  1 

c  3  : 

mo  v 

d  1  ,  1 

cmp 

dh  ,  2  3 

; am  I  at  the  end  of  the  Y  line? 

j  Z 

c  4 

;  yes 

add 

dh  ,  1 

;  no  p  e 

jmp 

c  1 

c4  : 

ret 

;  y  e  s  -  go  home  ! 

Count 

E  nd  p 

(Continued  on  next  page) 
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G3ITIG  Of  Life  (Listing  continued, 

text  begins  on  page  42) 

Update 

proc 

near 

;This  updates  the  generation  on  the  screen 

mo  v 

an  ,  0B0  0  0H 

;Get  screen  offset 

mo  v 

d  s  ,  a  x 

mo  v 

bx  ,  24*80*2-2 

;  loop  through  all  of  the  screen  but  last  line 

ul  : 

mo  v 

c  x ,  [bx] 

i  1  i  ne 

cmp 

ch , rev 

i  is  it  to  live? 

jnz 

u  2 

;  no 

mo  v 

cl , live 

;  yes 

j  nip 

u  3 

u  2  : 

mo  v 

cl  , d  e  a  d 

;  no 

u  3  : 

mo  v 

ch, dark 

; turn  off  reverse 

mo  v 

[bx]  , c  x 

;  put  it  back  on  the  screen 

sub 

b  x  ,  2 

;  loop  back  until  done  with  the  screen 

3  g 

ul 

ret 

;  go  back  to  caller 

Update 

endp 

cseg 

ends 

stack  segment  para  stack  'stack' 
db  30  dup (  ' s  tack  '  ) 
stack  ends 

end  End  Listing 
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Series  Expansion  in  Forth 


Series  expansions  are  widely  used  in 
computers  to  generate  precision 
non-linear  functions.  The  usual 
approaches  to  series  implementation  use  a 
lot  of  constants.  This  results  in  much  space 
being  used  for  headers  or  for  stuffing  all 
the  constants  into  arrays,  which  makes 
checking  and  adding  more  constants  awk¬ 
ward.  Also,  the  mechanics  of  computing 
each  series  varies  —  some  have  only  even 
and  others  only  odd  exponents,  some 
have  all  exponents,  some  begin  with  a 
constant  and  others  do  not,  etc. 

A  different  approach,  which  places 
coefficient-exponent  pairs  into  an  array 
while  preserving  readability  and  access,  is 
shown  in  screens  38-43,  at  right.  The 
algorithm  is  identical  for  all  series,  regard¬ 
less  of  first-term  constant  or  exponent 
pattern.  This  approach,  like  Dr.  Eaker’s 
Case  statement,  permits  the  programmer 
to  concentrate  on  the  results  rather  than 
on  the  mechanics. 

The  first  goal  is  to  compactly  store 
the  data,  which  consists  of  floating¬ 
point  coefficients  and  integer  exponents. 
SERIES-CONSTANTS  expects  on  the 
stack  the  number  of  terms  to  be  com¬ 
puted.  It  then  allots  space  for  this  num¬ 
ber  (1  byte)  plus  7  bytes  per  term  —  one 
byte  for  the  integer  exponent  and  6  bytes 
for  the  floating-point  coefficient.  This 
arrangement  limits  the  number  of  terms 
and  the  exponent  to  256,  which  would 
seem  adequate  for  most  needs.  A  header 
is  compiled  for  the  assigned  NAME  and 
the  number  of  terms  is  stored  in  the  first 
byte  ot  the  allotted  space. 

Next,  the  coefficients  and  exponents 
are  written  in  the  eminently  readable  for¬ 
mat  shown  in  Screen  227  (on  page  55) 
which  puts  them  on  the  stack  in  the  reverse 
of  the  order  shown,  with  the  smallest  ex¬ 
ponent  on  top.  Screen  228  contains  the 
code  to  obtain  the  proper  sign  and  to  re¬ 
duce  the  angle  to  within  less  than  360? 

These  constants  and  exponents  are 
next  loaded  into  the  allotted  space 
with  the  phrase  “  n  NAME  LOAD- 
CONSTANTS.  ”  The  number  of  constants 
to  be  stored  is  checked  against  the  num¬ 
ber  for  which  space  was  allotted,  and  the 
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Series  Expansion 

Screen  #  38 

0  (  Series  Expansion  Statement  bv  W.C.  Gates  11-21-82  ) 

1  0  VAL  NEXTADD  F0  FVAL  FACCUM 

2  0  VARIABLE  POWER  0  VARIABLE  NEXTEXP 

3  :  OVARS  FO  TO  FACCUM  0  POWER  1  ;  (Zero  FACCUM,  POWER  ) 

4 

5  (  NGET  does  z  add  ...  z  add  n  with  add+1  in  NEXTADD  ) 

6  :  NGET  DUP  1+  TO  NEXTADD  C3  ; 

7 

8  (  n  SERIES-CONSTANTS  name  defines  the  storage  space  for  an) 

9  (  array  which  contains  [number  of  terms]  [exp.  of  1st  term]  ) 

10  (  [FP  coefficient  of  Is  term]  [exp  of  2nd  termHnext  coeff.]  ) 

11  (  exponents  rise  monotonical ly,  but  gaps  OK  ) 

12  ;  SERIES-CONSTANTS 

13  < BUILDS  DUP  HERE  C!  7*1+  ALLOT  <  for  6-byte  floating-  ) 

14  D0ES>  ;  (  point  numbers  ) 

15  — > 


Screen  #  39 

0  (  Series  Expansion —  LOAD-CONSTANTS  ) 

1  (  ) 

2  (  LOAD-CONSTANTS  stores  the  pre-computed  coefficients  into  the  ) 

3  (  space  alloted  by  SERIES-CONSTANTS.  These  coefficients  must  be) 

4  (  on  the  stack  already,  together  with  the  exponent  for  each  ) 

5  (  Cn  exp[n]  Cl  expl  CO  expO  n  add  ...  for  example) 

6  :  LOAD-CONSTANTS  DUP  1+  TO  NEXTADD  (  store  add  of  2nd  byte  ) 

7  >R  DUP  R>  (  DUP  n  under  address  ) 

8  03  7PAIRS  (  fetch  allotted  n,  QUIT  if  not  same  > 

9  0  DO  (  DO  n  times  ) 

10  NEXTADD  C!  (  store  exponent  at  next  byte  ) 

11  NEXTADD  1+  TO  NEXTADD  (  point  to  next  byte  ) 

12  NEXTADD  F!  (  store  coefficient  ) 

13  NEXTADD  6  +  TO  NEXTADD  (  point  past  stored  coeff.  ) 

14  LOOP  ; 

15  —  > 


Screen  #  40 

0  (  Series  Expansion — continued  ) 

1  (  TERM  raises  z  to  the  power  stated  in  the  first  byte  of  each  ) 

2  (  term/constant  location,  starting  with  the  value  z~n  of  the  ) 

3  (  previous  term.  ) 

4 

5  (  z  zAn  ...  z  z~[n+x]  z^Cn+x]  ,  NEXTADD  points  to  exp.  ) 

6 

7  :  TERM 

8  NEXTADD  C3  NEXTEXP  !  (  store  target  exponent  ) 

9  BEGIN 

10  POWER  3  NEXTEXP  3=0=  (  current  exp.  =  target  exp?  ) 

11  WHILE  (  if  not,  ) 

12  F0VER  F*  1  POWER  +!  (  raise  exponent  1,  inc.  POWER  ) 

13  REPEAT  <  repeat  until  curr ent=target .  ) 

14  FDUP  ;  (  then  FDUP  and  exit.  ) 

15  --> 

OK 
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Screen  #41 

0  (  Series  Expansion  —  ADD-TO  > 

1 

2  (  ADD-TO  -fetches  the  next  coe-f-f icient  and  multiplies  it  with  ) 

3  (  zAn  on  TOS,  then  adds  result  to  FACCUM,  and  points  ) 

4  (  NEXTADD  to  exponent  o-f  next  term.  ) 

5 

6  (  z  zAn  zAn  ....  z  zAn  ) 

7 

8  :  ADD-TO 

9  NEXTADD  1+  TO  NEXTADD  (  point  to  coe-fficent  ) 

10  NEXTADD  F3  Ft  <  fetch  and  multiply  x  zAn  ) 

11  FACCUM  F+  TO  FACCUM  (  add  to  cumulative  total  ) 

12  06  NEXTADD  +  TO  NEXTADD  ;  (  point  to  exp.  of  next  term  ) 

13 

14  — > 

15 


Screen  #  42 

0  (  Series  Expansion —  SERIES  ) 

1  (  Used  as  z  Cnamel  SERIES  ...  for  value  z.  > 

2  (  number  of  terms  is  defined  in  Cnamel  ) 

3 

4  :  SERIES 

5  OVARS  >R  FI  R>  <  set  variables  to  0,  FI  to  stack  ) 

6  NGET  0  DO  (  get  #  of  terms  for  loop  ) 

7  TERM  ADD-TO  (  calculate  term  and  add  to  total) 

B  LOOP 

9  FDROP  FDROP  (  drop  calculation  values  ) 

10  FACCUM  ;  (  leave  accumulated  value  on  stack) 

11  ;S 

12 

13 

14 

15 


Screen  #  43 

0  (  SERIES  expansion —  BY-N  and  BY-EXP  ,  fetching/storing  exp.  ) 

1  (  BY-N  leaves  the  address  of  the  nth  exponent-coefficient  pair  ) 

2  (  used  as  . . . .  n  NAME— CF  BY— N  followed  by  F3  or  F!  ) 

3 

4  :  BY-N  2DUP  3  >  <  test  for  n  inside  array  ) 

5  IF  CR  ."  n  is  outside  array. “  QUIT  END IF 

6  2  +  SWAP  7  *  +  ;  (  point  to  coeff.  in  nth  term) 

7 

8  (  ..  n  NAME-CF  BY-EXP  leaves  the  address  of  coeff.  with  exp.  n  > 

9 

10  :  BY-EXP  NGET  SWAP  0  FLAG  !  (  n  to  TOS,  add+1  to  NEXTADD) 

11  BEGIN  DUP  NEXTADD  C3  =  <  compare  to  term  exp  ) 

12  IF  1  ELSE  OVER  FLAG  3  =  (no  more  than  n  terms  ) 

13  IF  CR  ."  Exponent  not  found."  QUIT  ENDIF 

14  0  1  FLAG  + !  NEXTADD  7  +  TO  NEXTADD  ENDIF  (  next  term  ) 

15  UNTIL  2DR0P  NEXTADD  1+  ;  ;S 

OK 


Screen  #  45 

0  (  Derivative  Calculations — N  derivatives  of  n-order  polynomial.) 

1  (  Method  from  Hoffman,  DDJ  April  81,  implm  by  W.C. Gates  Dec  B2) 

2  F0  FVARI ABLE  EVAL-P0INT  0  VARIABLE  POLY-ARRAY 

3  :  GEN. ARRAY 

( Continued  on  next  page) 


exponent-coefficient  pairs  are  stored  into 
the  space.  Only  one  header  is  required  for 
all  the  exponents  and  coefficients. 

Computation  is  done  by  SERIES, 
which  expects  a  floating-point  value  and 
the  beginning  address  of  the  data  space, 
left  by  NAME-CF  of  the  series.  The  first 
byte  is  the  number  of  terms,  which  is 
used  as  the  DO- LOOP  index.  TERM 
raises  the  power  of  the  base  value  until  it 
matches  the  next  stored  exponent.  ADD- 
TO  fetches  the  matching  coefficient,  mul¬ 
tiplies  it  with  the  raised  base  value,  and 
accumulates  the  total  in  ACCUM.  This 
sequence  is  repeated  n  times  to  generate 
and  add  up  n  terms.  Exponents  may  in¬ 
crease  in  any  monotonic  pattern.  A  series 
in  half-power  exponents,  frequently  en¬ 
countered  in  flow  measurement,  may  be 
generated  by  taking  the  square  root  of 
the  base  value  before  using  it  to  compute 
the  series. 

In  some  applications,  adaptive  control 
for  example,  it  may  be  necessary  to  modify 
the  series  coefficients  during  operation. 
This  feature  is  provided  by  BY-N,  used 
as  “n  NAME-CF  BY-N,”  which  leaves 
the  address  of  the  nth  coefficient  in  the 
series.  The  word  BY-EXP  similarly  leaves 
the  address  of  the  coefficient  of  the  term 
whose  exponent  is  n. 

Where  evaluation  of  polynomial  deri¬ 
vatives  is  required,  a  slower  and  less  com¬ 
pact  method  is  implemented,  in  Screens 
45-49  (pages  53-55).  The  polynomial 
coefficients  are  transferred  to  a  working 
array,  with  floating-point  0s  inserted  for 
the  absent  coefficients.  This  array  is  then 
processed  by  CALC.DERIVS,  resulting  in 
the  coefficient  values  being  replaced  by 
the  n  derivative  values,  including  the  value 
of  the  polynomial  itself  in  the  first  loca¬ 
tion.  The  values  of  the  n  derivatives  are 
then  fetched  as  required  using  N  DERIV. 
For  an  explanation  on  the  mathematical 
method,  see  the  article  by  R.A.  Hoffman 
in  Dr.  Dobb ’s  Journal,  April  1981. 

The  screens  provided  are  written  for 
a  floating-point  package  which  uses  a 
6-byte  format  for  floating-point  numbers. 
For  4 -byte  formats,  change  the  6s  and 
7s  to  4  and  5.  The  floating-point  coeffi¬ 
cients  are  handled  as  groups  of  bytes,  so 
the  program  is  indifferent  to  the  internal 
sign-exponent-mantissa  format. 


(Listing  begins  on  page  52) 
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53 


10  DUP 

HERE  DUP  POLY-ARRAY 

C! 

1+7*1+  ALLOT  ; 


(  highest  anticipated  order  ) 

(  beg.  address  to  POLY-ARRAY  ) 

(  store  highest  order  in  1st  byte  ) 
(  allot  space  -for  order+1  terms, 

(  each  of  which  is  exp-byte  plus  -float#  ) 


10  :  GET. ORDER 

1 1  DUP  C3 

12  1-7*1++ 

13  C3  ; 

14  GEN. ARRAY 

15  --> 


(  expects  add.  o-f  coe-f.  array,  fetches  order, 
(  which  is  exponent  of  last  term,  to  TOS 


(  allots  array  when  LQADed. 


Screen  #  46 

(  Derivative  Calculations  —  FILL. ARRAY  transfers  coeff’s  from  ) 
(  permanent  array  to  working  array,  filling  F0  for  absent  coefs) 


FILL. ARRAY  (  poly-arr, 

DUP  GET. ORDER  ( 

>R  OVER  R>  DUP  ROT  C! 

>R  1+  SWAP  1+  R>  1+  0  (  point 

DO  OVER  C3  I  =  (  print 

IF  DUP  I  SWAP  C! 

1+  DUP  6  +  SWAP  ROT  1+  DUP  6  + 

ROT  ROT  SWAP  >R 

F3  R>  F!  SWAP 

ELSE  DUP  7  +  SWAP 

DUP  I  SWAP  C! 

1+  >R  F0  R>  F!  (  but  tr 

THEN  (  array. 

LOOP  2DR0P  ;  — > 


(  poly-array-add  coef-array-add  ....  ) 

(  padd  cadd  n  ....  ) 

(  store  order  in  1st  byte  ) 
(  point  to  exp. bytes,  loop  n+1  times) 
(  print  exp,  test  for  equal  exp's  ) 
(  if  =,  move  exp.  ) 
1+  DUP  6  +  (  and  calc,  next  add’s  ) 


(  if  not  =  stuff  F0) 
(  point  to  next  work. add) 
(  but  try  again  at  same  loc  in  source) 
(  array.  ) 


Screen  #  47 

(  Derivative  Calculation  —  *FACS  multiplies  terms  by  n!  ) 


*FACS  (  empty  stack  ....  same  ) 

FI  POLY-ARRAY  3  DUP  16  +  SWAP  (  Fl>stack,  point  to  A2  term) 


C3  1+  2 
DO 

I  SWAP  DUP  DUP  >R  >R  >R 
S->D  D>F 
F*  FDUP  R>  F3  F* 

R>  F! 

R>  7  + 

LOOP 

DROP  FDROP  ; 


(  n+1,  2  =  for  2  to  n  ) 

(  I>stk,  add’s  to  ret.  stk  ) 

(  convert  I  to  floating  #  ) 

(  x  prev.  ,  x  coeff,  ) 

(  store  product  back  ) 

(  point  to  next  coeff.  ) 

(  leave  stack  clean  ) 


Screen  #  48 

0  (  Derivatives  Calculation  —  CALC.DERIVS  performs  calculations  ) 

1  (  replacing  CDef’s  with  values  in  working  array.  ) 

2  :  CALC.DERIVS  (  <point  of  evaluation — F#>  <ser ies-name>. . ) 

3  >R  EVAL-POINT  F!  (  store  XI  value  to  EVAL. POINT  ) 

4  POLY-ARRAY  3  DUP  R>  (  work-add  to  stack,  R>  series-array-add) 

5  FILL. ARRAY  C3  DUP  (  coefs  into  work-array,  filling  FO’s) 

6  1-  SWAP  0  (  ...  N-l  N  0  ) 


DO  DUP  DUP  I  1-  SWAP 
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Series  Expansion 

(Listing  continued,  text  begins  on  page  52) 


8  DO  (  limit  is  1st  index,  index  is  ) 

9  11+  POLY-ARRAY  3  BY-N  F3  (  N-l  minus  iteration  #  ) 

10  EVAL-POINT  Fa)  Ft  <  prev.  coef  f .  x  point  value  ) 

11  I  POLY-ARRAY  3  BY-N  DUP  >R  (  add  above  to  current  coeff) 

12  F3  F+  R>  F! 

13  1-  -1  +L00P  DROP 

14  LOOP 

15  IFACS  ;  — >  (  each  coef  x  n  -factorial) 

Screen  #  49 

0  (  Derivatives  Calculation —  DERIV  fetches  nth  derivative  value  ) 

1  (  checks  for  out-of  bounds  request,  non-destructi vely  ) 

2  :  DERIV 

3  DUP  POLY-ARRAY  3  DUP 

4  ROT  SWAP  C3  > 

5  IF  5  SPACES  . "  Requested  too  high  a  derivative.  "  2DR0P 

6  ELSE  2+  SWAP  7  *  +  F3 

7  THEN  ;  ;S 

8 

9  USE  OF  DERIVATIVES  CALCULATION 

10  Define  largest  order  polynomial  to  be  used;  add  1  to  order  and 

11  insert  this  value  into  Screen  45,  line  4.  Then  45  LOAD. 

12 

13  <F#evaluation  point)  <ser ies-coef f-name>  CALC. DERIVS. . .  does 

14  the  calculations,  N  DERIV  puts  the  nth  derivative  value  on 

15  the  stack. 


OK 

Screen  #  227 


0  (  Floating  Point —  SINE  ) 

1  6  SERIES-CONSTANTS  SINE-CF 

2  (  coefficients 

3 

4  -2.50521084  X  -8 

5  2.75573192  X  -6 

6  -1.98412698  X  -4 

7  8.33333333  X  -3 

8  -1.66666667  X  -1 

9  FI 

10  6  SINE-CF  LOAD-CONSTANTS 

11  :  [SINE!  SINE-CF  SERIES  ; 

12 

13  (  "X"  is  used  for  floating  point 

14  (  reading  hex  keypads.  FI  is  1.0 

15  — > 


(  allot  storage  space  ) 
exponents  ) 

11  (  monotonical ly  ) 

9  (  decreasing  ) 

7  (  exponents  ) 

5 
3 
1 

(  n  Cnamel  LOAD-CONSTANTS  ) 


entry  to  permit  using  “E"  in) 
floating  point.  ) 


Screen  #  228 

0  (  Trig  Package  —  SINE  continued  ) 


1 

2  :  ANGLE-PREP 

3  FPI  F/M0D  FABS  FIX  D->S 

4  DUP  0=  IF  DROP  ELSE  >R 

5  FI  R>  0  DO 

6  FI  FMINUS  FI  LOOP 

7  FI  END  IF  •, 

8 

9  ;  FSIN 

10  DEG-RAD  0=  IF  DEG>RAD  END IF 

11  ANBLE-PREP  CSINE]  ; 

12 

13  ;  S 

14 

15 


(  convert  to  rads  if  rqd  ) 
(  get  #  of  half  circles  ) 
(  x  -1,  is  -  for  2nd  half  ) 
(  +1  for  1st,  -1  for  2nd  ) 
(  apply  sign  to  angle  <180  d.  ) 
(  calculate  sine  series  ) 


(  using  degrees?  convert  >rads) 
(  strip  full  turns,  calc,  and  ) 
(  apply  sign,  calc,  value  ) 
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End  Listing 


Fast  Matrix  Operations 

In  Forth,  Part  1 


It  is  fairly  well-known  that  among 
various  languages  having  software  - 
implemented  floating  point,  there  is 
little  practical  difference  in  the  speed  at 
which  number-intensive  programs  run. 
The  reason  for  this  small  difference  is 
that  a  large  proportion  of  total  program 
run  time  is  spent  on  the  floating-point 
routines  that  are  written  in  assembly  lan¬ 
guage  and  are  therefore  essentially  the 
same  for  every  language.  Since  most  lan¬ 
guages  developed  under  this  condition,  it 
is  doubtful  that  any  need  for  faster  numer¬ 
ical  operations  influenced  their  evolution. 
With  the  advent  of  hardware-implemented 
floating  point  in  the  form  of  numeric  co¬ 
processors  such  as  the  8087,  80287,  and 
16081,  a  situation  arises  in  which  most  of 
the  popular  numerical  languages  are  inca¬ 
pable  of  efficiently  utilizing  their  speed. 
This  deficiency  is  most  true  of  interpreted 
languages  such  as  BASIC  and  APL. 

In  my  quest  for  a  faster  alternative,  I 
have  found  what  I  believe  to  be  an  ideal 
in  an  unpopular  floating-point  language, 
Forth.  More  specifically,  I  have  found 
Polyforth  for  the  IBM  PC  to  be  best  for 
floating-point  applications  because  it  uses 
the  8087  register  stack  as  an  extra  Forth 
stack  and  it  includes  the  8087  instruction 
set  in  its  assembler.  By  using  the  assem¬ 
bler,  it  is  not  unusual  for  a  numerically 
intensive  program  to  run  100  times  faster 
in  Forth  than  in  standard  BASIC. 

From  the  viewpoint  of  programming 
convenience,  APL  is  the  Rolls  Royce  of 
numeric  languages.  The  enthusiasm  of 
APL  users  easily  matches  that  of  Forth 
users,  although  each  group  loves  their  lan¬ 
guage  for  entirely  different  reasons.  APL 
is  characterized  by  syntactically  simple 
commands  that  operate  on  entire  arrays 
rather  than  on  single  numbers.  Generally, 
the  shortest  program  for  performing  a 
given  task  can  be  written  in  APL.  APL 
does,  however,  have  a  reputation  for 
being  slow. 

I  have  found  that  it  is  not  at  all  diffi¬ 
cult  to  write  Forth  programs  that  resemble 
APL  commands.  For  example,  consider 
the  following  phrase  for  performing 
matrix  multiplication  in  Forth: 


by  Steven  A.  Ruzinsky 


Steven  A.  Ruzinsky,  2110  S.  Austin  Blvd., 
Cicero,  Illinois  60650. 


’  A  ’  B  ’  C  A* 

Here,  A*  is  the  matrix  multiplication 
operator  and  A,  B,  and  C  are  arbitrary 
conformable  matrices.  In  algebraic  nota¬ 
tion,  C  =  AB.  The  advantage  of  Forth 
over  APL  is,  of  course,  speed.  The  pro¬ 
gram  represented  above  will  multiply  two 
lOth-order  square  matrices  in  0.1  seconds. 
APL  users  are  invited  to  present  bench¬ 
marks  for  comparison. 

In  this  first  of  a  three-part  series, 
some  fundamental  Forth  matrix  utilities 
will  be  presented.  In  the  second  install¬ 
ment,  programs  for  the  classical  matrix 
operations  such  as  matrix  addition,  multi¬ 
plication,  and  inversion,  plus  some  equally 
useful  but  more  unusual  operations,  will 
be  presented.  The  third  part  will  be  con¬ 
cerned  with  matrix  applications.  If  reader 
response  is  favorable,  more  items  on  ma¬ 
trix  applications  could  be  forthcoming. 

These  programs  require:  (1)  the  IBM 
PC  with  more  than  64  KB,  preferably 
320  KB,  of  RAM;  (2)  an  8087  numeric 
coprocessor  installed  in  the  empty  socket 
next  to  the  8088  (dipswitch  SW1-2  must 
be  off);  and  (3)  Polyforth  Level  2  for  the 
IBM  PC  from  Forth,  Inc. 


The  Programs 

The  fundamental  programs  are  pre¬ 
sented  in  screens  207  to  209  (page  57).  A 
description  of  these  programs  follows: 

a!,  a@,  etc.  —  Fast  concatenated  16- 
bit  variable  stores  and  fetches.  These  will 
be  used  within  many  of  the  succeeding 
programs. 

matrix  —  Defines  a  character  string  as 
a  matrix.  Usage  example: 

10  20  matrix  X 

Here,  X  is  defined  as  a  matrix  of  10  rows 
by  20  columns.  Such  a  matrix  has  the  fol¬ 
lowing  properties: 

•  The  data  contained  in  the  matrix  resides 
outside  the  Forth  dictionary  and  can 
occupy  all  available  memory  beyond 
the  first  64  KB  segment  of  RAM. 

•  Two  64-bit  numbers  can  be  stored  in 
each  matrix  element.  Thus,  X  in  the 
above  example  can  be  considered  as 
two  interlaced  matrices  of  real  numbers 
or  a  single  matrix  of  complex  numbers. 
Operators  subscripted  with  1  and  2  will 
respectively  apply  to  the  first  or  sec¬ 
ond  of  the  two  “interlaced”  matrices, 


whereas  unsubscripted  operators  will 
apply  to  the  matrix  as  a  whole. 

•  Indexing  of  the  matrix  elements  is 
from  (0,0)  to  (m-l,n-l)  where  m  is 
the  number  of  rows  and  n  is  the  num¬ 
ber  of  columns. 

variable  —  Defines  a  character  string 
as  a  16-byte  variable  outside  the  first  64 
KB  of  RAM.  Usage  example: 

variable  Y 

forget  —  Erases  a  matrix  or  variable 
in  a  manner  analogous  to  the  standard 
Forth  word  FORGET.  Usage  example: 

forget  X 

dim@  —  Retrieves  the  dimensions  of 
the  matrix  and  puts  them  on  the  parame¬ 
ter  stack  with  the  number  of  columns  on 
top  and  the  number  of  rows  underneath. 
Usage  example: 

’  X  dim® 

dim!  —  Changes  the  dimension  of  a 
matrix.  The  number  of  matrix  elements, 
however,  must  not  increase.  Usage 
example: 

200  1  ’  X  dim! 

!1,  !2,  !!  —  Are  matrix  element  and 
variable  stores.  !1  and  !2  transfer  the  top 
number  of  the  numeric  stack  to  the  in¬ 
dicated  position  in  the  matrix  element  or 
variable.  ! !  is  functionally  equivalent  to 
!2  !1.  Usage  examples: 

3.14  5  15  X  !1 

2.72  1.23  Y  ! ! 

@1,  @2,  —  Are  matrix  element 

and  variable  fetches.  Usage  examples: 

5  15  X  @2 

Y  @1 

EXC1,  EXC  —  Are  exchange  matrix 
elements  or  variables.  Usage  examples: 

5  15  X  3  2  X  EXC1 

Y  8  9  X  EXC1 

A  few  final  notes:  Because  floating¬ 
point  numbers  and  integers  are  stored  on 
separate  stacks,  their  order  before  an 
operator  makes  no  difference.  Thus,  these 
phrases  are  equivalent: 

123.456  654.321  3  7  X!! 

3  7  123.456  654.321  X!! 

3  123.456  7  654.321  X  !  ! 

Also,  the  use  of  ’  should  be  commented  on. 
This  is  called  “tick”  and  it  places  the  dic¬ 
tionary  address  of  the  word  following  it 
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onto  the  parameter  stack.  ’  is  for  use  out¬ 
side  a  colon  definition.  Inside  a  colon  defi¬ 
nition  [’]  must  be  substituted.  ’  and  [’] 
are  used  extensively  to  pass  subroutines. 


Mr.  Ruzinsky,  in  an  attempt  to  demon¬ 
strate  the  floating-point  speed  that  one 
can  achieve  with  Forth,  brought  to  our 
attention  the  article  “Benchmarking  the 
8087  Numeric  Coprocessor’’  in  the  March 
1983  issue  of  Personal  Computer  Age.  In 
it,  G.  Scott  Owens  provided  some  bench¬ 
marks  for  the  IBM  PC  with  an  8087  co¬ 
processor  (and  some  for  the  IBM  and 
other  machines  without  the  8087).  The 
fastest  times  obtained  for  his  floating¬ 
point  routine  (a  mixture  of  various  func¬ 
tions  such  as  sine,  cosine,  and  squareroot) 
were:  IBM  Pascal  with  an  8087  -  6  sec¬ 
onds;  and  compiled  IBM  BASIC  with  an 
8087  -  10  seconds  for  single  precision 
and  13  seconds  for  double  precision.  (The 
8087  software  in  those  cases  was  from 
Microware.)  Mr.  Ruzinsky  wrote  a  Forth 
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0  (  FPBENCH  in  Poly-forth,  Double  Free.,  2.625  sec./500  iters.  ) 

1  (  Note:  SIN,  COS,  EX,  #IN,  and  4ARRAY  are  author  written  > 

2  (  routines  that  are  not  included  in  standard  Poly-forth.  ) 

3 

4  :  4ARRARY  CREATE  8  *  10  +  ALLOT  ;  CODE  W  INC  W  INC  0  POP  0  SHL 

5  0  SHL  0  SHL  W  0  ADD  0  PUSH  NEXT 

6  10  4 ARRAY  X  LVARI ABLE  A 

7  :  L00F'2  10  1  DO  I  X  L3  FDUP  F*  PI  F/  A  L'  LOOP  ; 

8  :  SBR  PI  2.1  F/  FDUP  SIN  1  X  L!  FDUP  COS 

9  2  X  L!  FDUP  FDUP  F*  3  X  L!  FDUP  FSQRT  4  X  LI 

10  FDUP  EX  5  X  L‘  FDUP  LN  6  X  L !  FDUP  7  X  LI 

11  FDUP  PI  F*  8  X  LI  SIN  2. O  F*  9  X  L I  ; 

12  :  FPBENCH  CR  . "  THIS  IS  A  NUMBER  CRUNCH INS  SPEED  TEST  " 

13  CR  . "  ENTER  THE  NUMBER  OF  ITERATIONS  “  #IN 

14  COUNTER  SWAP  0  DO  SBR  L00P2  LOOP  COUNTER  SWAP 

15  -  >N  1000.0  F/  CR  ."  ELAPSED  TIME  =  "  3  F.  ; 

Figure  1. 

Floating-point  benchmark  routine  in  Forth. 


version  on  his  own  system  of  the  floating¬ 
point  routine  used  by  Mr.  Owens  and  ob¬ 
tained  a  time  of  2.625  seconds.  His  Forth 
routine  is  printed  in  Figure  1  (above). 

■•j  (Listing  begins  below) 


Fast  Matrix  Operations  (Text  begins  on  page  56) 

207  LIST 


o 

VARIABLE 

a 

CODE 

a  ! 

0 

POP 

a 

STA 

NEXT 

1 

CODE 

a0 

a 

LDA 

O 

PUSH 

NEXT 

n 

X- 

VARIABLE 

b 

CODE 

b  ! 

0 

POP 

b 

STA 

NEXT 

3 

CODE 

b0 

b 

LDA 

0 

PUSH 

NEXT 

4 

VARIABLE 

c 

CODE 

c  ! 

0 

POP 

c 

STA 

NEXT 

5 

CODE 

C0 

c 

LDA 

0 

PUSH 

NEXT 

6 

VARIABLE 

i 

CODE 

i  ! 

0 

POP 

i 

STA 

NEXT 

7 

CODE 

i  0 

i 

LDA 

0 

PUSH 

NEXT 

8 

VARIABLE 

J 

CODE 

j  ! 

0 

POP 

j 

STA 

NEXT 

9 

CODE 

j  0 

j 

LDA 

0 

PUSH 

NEXT 

10 

VARIABLE 

k 

CODE 

k  ! 

0 

POP 

k 

STA 

NEXT 

11 

CODE 

k0 

k 

LDA 

o 

PUSH 

NEXT 

12 

VARIABLE 

m 

CODE 

m ' 

0 

POP 

m 

STA 

NEXT 

13 

CODE 

m0 

m 

LDA 

0 

PUSH 

NEXT 

14 

VARIABLE 

n 

CODE 

n  ! 

0 

POP 

n 

STA 

NEXT 

15 

CODE 

n0 

n 

LDA 

0 

PUSH 

NEXT 

208  LIST 

0  <  Matrix  Defining  Operators  ) 

1  ~  VARIABLE  (here)  1  (here)  ! 

2  :  here  (here)  0  ; 

3  ~  :  forget  ABORT"  ?"  B/H  -  DUP  ’S  H  2+  0  WITHIN 

4  CAN’T  H  !  CURRENT  CONTEXT  2+  DO  I  BEGIN 

5  0  DUP  HERE  <  UNTIL  I  !  2  /LOOP  0  (here)  !  ; 

6  ■'*  :  allot  here  +  (here)  !  ; 

7  ~  :  variable  here  CONSTANT  1  allot  ; 

8  ~  :  matrix  CREATE  here  ,  SWAP  2DUP  ,  .  *  al 1 ot  ; CODE  O  POP 

9  1  POP  2  W)  1  ADD  4  W)  MUL  1  O  ADD  O  PUSH  NEXT 

10  VARIABLE  adr  ^  CODE  adr0  adr  LDA  O  PUSH  NEXT 


(Continued  on  next  page) 
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11  ~  CODE  adr !  O  POP  adr  STA  NEXT 

12  '''  CODE  dimS  W  POP  W  )  O  MOV  adr  STA  2  W>  O  MOV  O  PUSH 

13  4  W>  O  MOV  O  PUSH  NEXT 

14  -  CODE  dim!  W  POP  W  )  O  MOV  adr  STA  O  POP  O  4  W)  MOV  O  POP 

15  O  2  W)  MOV  NEXT 

09  LIST 

O  (  Matrix  Element  Fetch,  Store  and  Exchange  ) 

1  CODE  ! 1  0  DS  SSG  DS  POPS  R64  65520  FSTP  O  DS  LSG  NEXT 

2  CODE  31  O  DS  SSG  DS  POPS  R64  65520  FLD  O  DS  LSG  NEXT 

3  CODE  ! 2  O  DS  SSG  DS  POPS  R64  65528  FSTP  O  DS  LSG  NEXT 

4  CODE  32  O  DS  SSG  DS  POPS  R64  65528  FLD  O  DS  LSG  NEXT 

5  CODE  ! !  O  DS  SSG  DS  POPS  R64  65528  FSTP  R64  65520  FSTP 

6  O  DS  LSG  NEXT 

7  CODE  33  0  DS  SSG  DS  POPS  R64  65520  FLD  R64  65528  FLD 

8  O  DS  LSG  NEXT 

9  *'•  CODE  EXC  65520  #  W  MOV  0  DS  SSG  DS  POPS  R64  8  W>  FLD  R64 

10  W  )  FLD  2  DS  SSG  DS  POPS  R64  8  W>  FLD  R64  W  )  FLD  1  DS  SSG 

11  2  DS  LSG  R64  W  )  FSTP  R64  8  W>  FSTP  1  DS  LSG  R64  W  )  FSTP 

12  R64  8  W)  FSTP  O  DS  LSG  NEXT 

13  CODE  EXC1  65520  #  W  MOV  O  DS  SSG  DS  POPS  R64  W  )  FLD  2  DS  SSG 

14  DS  POPS  R64  W  )  FLD  1  DS  SSG  2  DS  LSG  R64  W  )  FSTP  1  DS  LSG 

15  R64  W  )  FSTP  O  DS  LSG  NEXT  End  Listing 
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Yes,  You  Can 

IVace  Through  BDOS 


Letters  to  Dr.  Dobb  have  shown  an  in¬ 
terest  in  using  the  DDT  Trace  function 
to  examine  the  operation  of  BDOS 
functional  calls.  The  last  word  on  the  sub¬ 
ject  (February  1983,  page  1 1 )  was,  “This 
will  never  work  no  matter  how  clever  one 
is.  .  .  .”  Who  could  resist  a  challenge  like 
that? 

Demonstrating  the  Problem 

Let’s  try  to  Trace  through  a  very 
simple  BDOS  function  and  see  what  the 
problem  is.  BDOS  function  31  is  a  good 
candidate  for  this  because  it  only  fetches 
the  disk  parameter  address  and  puts  it  in 
the  H/L  register  pair.  The  test  program 
(TRACE. ASM  —  shown  in  Listing  1  below) 
contains  the  minimum  elements  necessary 
to  demonstrate  the  problem. 

(1)  It  initially  clears  the  H/L  pair  (so  we 
know  the  non-zero  result  was  not 
left  over  from  a  previous  run). 

(2)  It  calls  BDOS  function  3 1 . 

(3)  It  executes  an  instruction  (NOP) 
after  it  returns. 

(4)  It  has  an  easily  recognized  end. 

The  DDT  session  is  separated  into 
procedures  to  make  it  easier  to  follow. 

In  Procedure  1  (page  61),  I  booted  a 
48K  system  (system  size  is  important) 
and  used  DDT  to  get  the  test  program  in 
memory.  The  List  command  disassembled 
the  object  code  in  memory,  showing  that 
the  program  was  actually  there.  The  Go 
command  executed  the  program  (from 
100  to  108)  and  the  Examine  (X)  com¬ 
mand  showed  that  the  H/L  pair  had  B47E 
in  it  when  the  test  program  was  finished. 
B47E  is  in  fact  the  address  of  the  disk 
parameter  header  for  this  particular  CP/M 
configuration.  If  you  run  this  program  on 
your  system,  you  will  probably  get  a  dif¬ 
ferent  number  in  the  H/L  pair.  If  you  are 
skeptical,  you  can  examine  memory  begin¬ 
ning  at  that  location  and  verify  that  it  is 
actually  a  disk  parameter  header. 

The  G 100, 100  command  gets  the 
program  counter  back  to  the  beginning  of 
the  program,  and  TOC  is  the  command  to 
Trace  twelve  lines  (DDT  thinks  in  hex). 
Notice  that  the  H/L  pair  was  cleared, 
Register  C  was  set  to  31  (IF  hex),  and 
the  BDOS  routine  was  called. 


by  Do-While  Jones 


Do -While  Jones,  324  Traci  Lane,  Ridge¬ 
crest,  California  93555. 


Location  0005  always  contains  a  jump 
to  the  BDOS  section  of  CP/M.  Since  the 
location  of  BDOS  depends  upon  memory 
size,  this  address  will  vary  depending 
upon  system  size.  Whenever  you  boot  the 
CP/M  system,  it  will  always  make  sure 
the  jump  command  at  0005  is  set  to  the 
proper  address.  In  the  48  K  system  I  was 
using,  this  address  was  9500.  The  Trace 
display  showed  the  jump  to  9500,  and 
the  first  few  instructions  in  BDOS,  but 
the  line  following  JMP  A506showsaNOP. 
Closer  inspection  shows  the  program 
counter  appeared  to  go  from  9BA7  directly 
to  0108.  I  say  “appeared”  because  the 
intermediate  steps  really  were  executed. 
We  can  tell  this  by  the  fact  that  the  H/L 
pair  has  the  right  answer  (B47E)  in  it. 

The  invisible  gap  between  9BA7  and 
0108  is  the  sequence  of  instructions  that 
some  readers  are  interested  in  seeing. 

To  Trace  or  Not  To  Trace  .  .  . 

Although  it  is  possible  to  Trace 
through  BDOS,  I  do  not  recommend  that 
you  do  it  routinely.  DDT  is  designed  not 
to  Trace  through  BDOS  functions  for 


your  convenience.  If  you  defeat  this  fea¬ 
ture  frequently,  you  will  just  make  your 
own  life  more  difficult. 

Inexperienced  programmers  use  Trace 
at  the  first  sign  of  trouble.  They  hit 
control-P,  T100  and  start  looking  through 
reams  of  paper  that  slowly  emerge 
from  the  printer.  That  is  not  a  very  effi¬ 
cient  way  to  debug  a  program,  especially 
if  it  contains  something  equivalent  to 
“FOR  1=  1  TO  500.” 

The  easier  way  to  debug  a  program 
is  to  use  break  points.  Use  the  “G”  com¬ 
mand  to  execute  a  small  portion  of  the 
program.  When  DDT  finishes  executing 
that  section,  it  will  return  with  the  “  *  ” 
prompt,  which  is  your  cue  to  use  “X”  to 
examine  registers  or  “D”  to  display  mem¬ 
ory.  If  you  have  written  your  program  in 
modular  form,  there  will  be  longer  places 
to  stop  and  examine  the  results.  For  ex¬ 
ample,  if  you  have  a  module  which  is 
supposed  to  convert  hex  numbers  into 
BCD  form,  then  you  can  stop  the  pro¬ 
gram  just  before  the  routine  to  see  what 
hex  number  is  going  into  the  routine  and 
see  if  the  BCD  number  that  came  out  is 


Simple  Program  for 
TVace  Demonstration 


T 

y 

TRACE.  ASM 

IS  FEBRUARY  1983 

DO-WHILE  JONES 

' 

T 

THIS  IS  USED  TO  DEMONSTRATE  HOW  TO  TRACE  THROUGH 

BDOS  CALLS. 

T 

GLOBAL  ADDRESSES 

0005  = 

BDOS  EQU 

0005H 

0100 

ORG  100H 

0100  210008 

0103  0E1F 

0105  CD0500 

0108  00 

LXI  Hi0 

MV I  Ci 31 

CALL  BDOS 

NOP 

!  CLEAR  THE  H/L  PAIR 

1  GET  ADDRESS  OF  DISK  PARAMETERS 

1  USING  BDOS  COMMAND  31 

5  DUMMY  OP  CODE 

0189  C30901  SELF:  JMP  SELF  ;  DO  FOREVER  LOOP 

010C  END 

Listing  1 . 


60 

318 


Dr.  Dobb’s  Journal,  Number  80,  June  1983 


correct.  Don’t  Trace  through  the  whole 
routine  unless  the  BCD  answer  is  wrong. 
Then  it  makes  sense  to  Trace  to  see  why 
it  gave  the  wrong  answer.  If  you  try  to 
use  “G”  to  execute  a  portion  of  a  routine 
and  never  see  the  “  *  ”  prompt,  it  means 
the  program  has  gone  to  “never-never 
land.”  Then  you  might  want  to  Trace  to 
see  where  you  PUSHed  without  a  POP  in 
a  subroutine,  or  where  you  selected  the 
wrong  condition  for  a  conditional  jump. 
But  it  is  best  to  try  to  isolate  the  error 
using  break  points  before  using  Trace. 

Do-While’s  Rule: 

Never  Trace  more  than  you  have  to. 

DDT  Saves  You  From  Yourself 

The  good  folks  at  Digital  Research 
put  a  lot  of  thought  into  the  DDT  pro¬ 
gram.  They  foresaw  users  trying  to  Trace 
through  a  program  which  contains  a 
BDOS  call  to  output  to  the  console  (or 
worse  yet,  read  a  sector).  They  knew  how 


frustrated  the  user  would  be  if  the  screen 
filled  up  with  dozens  of  lines  of  BDOS 
code.  On  those  rare  occasions  when  I 
have  resorted  to  Trace,  and  have  happened 
to  Trace  through  a  BDOS  command,  I 
have  been  very  grateful  that  DDT  turned 
off  the  display  until  the  BDOS  function 
returned  control  to  my  own  program. 

Normally  you  should  not  care  what 
the  BDOS  does  internally.  All  you  care 
about  is  that  the  return  parameters  are 
correct.  You  can  find  that  out  by  putting 
a  break  point  immediately  after  the 
BDOS  call.  Then  you  can  examine  regis¬ 
ters  (or  memory)  to  see  what  it  did,  with¬ 
out  having  to  try  to  figure  out  how  it  did 
it.  Be  sure  to  check  the  flag  register. 
There  are  times  when  BDOS  returns  with 
the  accumulator  =  00,  but  the  zero  flag 
is  not  set.  Since  the  JZ  (Jump  on  Zero) 
instruction  looks  at  the  zero  flag  rather 
than  the  contents  of  the  accumulator, 
your  program  may  not  branch  to  the 
desired  routine  unless  you  checked  the 
zero  flag  with  ANA  A. 


Is  There  Ever  A  Proper  Time 
to  Trace  BDOS  Calls? 

There  has  only  been  one  time  that  I 
ever  found  it  necessary  to  Trace  a  BDOS 
function.  I  wrote  an  extension  to  CP/M 
2.2  which  allowed  data  to  be  displayed 
simultaneously  on  the  console  screen  and 
stored  in  a  disk  file.  In  this  case  I  tried  to 
call  some  BDOS  routines  from  BIOS,  and 
the  program  crashed  because  the  BDOS 
is  not  reentrant.  I  needed  to  find  out 
why  it  was  crashing  and  how  to  avoid  it. 
1  Traced  through  enough  of  BDOS  to  find 
out  what  prevented  the  subroutine  from 
returning,  and  fortunately  I  was  able  to 
find  other  entry  points  which  allowed  me 
to  use  the  BDOS  subroutines  to  write  a 
sector  and  close  a  file.  Procedure  2  (page 
62)  shows  the  method  I  used. 

The  Trick  — 

Two  CP/M  Systems  at  Once 

After  demonstrating  the  problem 
using  Procedure  1 , 1  went  back  to  the  sys- 


Procedure  1. 

ASK  VERSION  2.2  CP/M 


A>  DDT  TRACE. HEX 
DDT  VERS  2.2 
NEXT  PC 
010C  0000 
-LI  00,  10B 


0  1  00 

LX  I 

H,  0000 

0 1 03 

MVI 

C,  IF 

0105 

CALL 

0005 

0108 

NOP 

0109 

010C 

IMP 

0109 

-01.00,  109 
*0 1 09 
-X 


C0Z1M0E1 10 

A=7E 

B=B400 

0=0000 

H=B47E 

S=0100 

P=0109 

JMP 

0109 

-0100, 100 
+0 1 00 
-TOC 

C0Z 1M0E1 10 

A=7E 

B=B400 

0=0000 

H=B47E 

S=0100 

P=0100 

LX  I 

H, 0000 

C0Z  .1.M0E1 

10 

A=7E 

B=B400 

D=0000 

H=0000 

S=0100 

P=0 1 03 

MVI 

C,  IF 

C0Z1M0E1 

10 

A=7E 

B=B41F 

0=0000 

H=0000 

S=0100 

P=0 1 05 

CALL 

0005 

C0Z1M0E1 

10 

A=7E 

B=B41F 

D— 0000 

H=0000 

S=00FE 

P=0005 

JMP 

9500 

C0Z1M0E1 

10 

A=7E 

B-B4 1 F 

0=0000 

H=0000 

S=00FE 

P=9500 

JMP 

3BA2 

C0Z1M0E1 

10 

A=7E 

B-B4 1 F 

0=0000 

H=0000 

S=00FE 

P=9BA2 

XTHL 

C0Z1M0E1 

10 

A=7E 

B=B4 1 F 

0=0000 

H=0108 

5=00FE 

P=9BA3 

SHLD 

A44  A 

C0Z1M0E1 

10 

A— 7E 

B==B41F 

0=0000 

H=010S 

S=00FE 

P=9BAB 

XTHL 

C0Z1M0E1 

10 

A-7E 

B—B4 1.  F 

D=0000 

H=0000 

S=00FE 

P=3BA7 

JMP 

A506 

C0Z1M0E1 

10 

A-7E 

B-B400 

0=0000 

H=B47E 

S=0100 

P=0 1 08 

NOP 

C0Z1M0E1 

10 

A=7E 

B-B400 

0=0000 

H=B47E 

S=0100 

P=0109 

JMP 

0109 

C0Z  1.M0E1 

10 

A=7E 

B--B400 

0=0000 

H=B47E 

S=0100 

P=0 1 09 

JMP 

0109+0109 

-G0 
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tem  and  PIPed  the  TRACE. HEX  file  over 
to  another  disk,  which  had  a  different 
size  CP/M  system  on  it.  I  had  an  old  disk 
with  a  32K  system  on  it  that  I  had  SYS- 
GENed  when  1  only  had  32K  of  memory 
in  my  system.  So,  without  turning  off  the 
power,  I  cold-booted  this  32K  disk.  This 
put  a  32K  CP/M  system  in  memory, 
while  leaving  a  copy  of  the  48 K  system 
there,  too. 

Procedure  2  gave  results  that  were 
similar  to  Procedure  1,  but  they  were  not 
identical.  The  H/L  pair  returned  the  value 
747E,  which  is  exactly  16K  lower  than 
B47E  because  the  32K  system  is  16K 
smaller  than  the  48K.  system.  Also,  the 
.IMP  instruction  at  location  0005  sent  the 
program  to  5500  instead  of  9500. 

The  BDOS  routine  at  9500  is  still  in 
memory  but  DDT  doesn’t  know  that.  So 
look  what  happens  if  we  change  CALL 
0005  to  CALL  9500.  We  can  reset  the 


program  counter  to  the  beginning  of  the 
test  program  with  G  100,100  and  Trace  a 
bunch  of  lines  (36  hex  is  enough). 

This  time  it’s  all  there!  After  the  JMP 
A506,  the  program  counter  goes  to  A506, 
rather  than  skipping  down  to  0108. 

The  group  of  instructions  up  to  P= 
A546  PCHL  is  the  BDOS  entry  routine 
which  stores  parameters,  sets  up  the 
BDOS  stack,  and  jumps  to  the  selected 
BDOS  routine.  BDOS  function  31  itself  is 
only  three  lines. 

LHLD  B2BB 
SHLD  A845 
RET 

The  nine  lines  after  that  are  the  BDOS 
exit  routine,  which  restores  parameters, 
restores  the  user  stack,  and  fetches  the 
answer  from  A845. 

The  desired  Trace  is  shown  in  Pro¬ 
cedure  3  on  page  64. 


Why  It  Works 

Using  a  second  CP/M  system  does 
two  things  that  permit  a  successful  Trace 
of  BDOS  functions: 

(1)  DDT  uses  the  32K  BDOS  stack  and 
32K  BDOS  reserved  memory  loca¬ 
tions  while  the  test  program  is  using 
the  48  K  BDOS  stack  and  reserved 
memory  locations. 

(2)  DDT  inhibits  the  display  when  the 
user  program  counter  is  in  the  32K 
BDOS,  but  it  doesn’t  care  that  the 
program  counter  is  in  the  reserved 
area  of  the  48K  BDOS.  Therefore  it 
permits  the  program  flow  to  be  dis¬ 
played. 

There’s  nothing  really  magical  about 
48K  and  32K.  You  could  use  any  two 
CP/M  systems,  providing  they  don’t  over¬ 
lap.  You  probably  have  a  20K  (or  24K) 


h>  P I  P  B :  -TRACE.  HEX  Procedure  2. 

32K  VERSION  2.2  CP/M 


A>  DDT  TRACE.  HEX 
DDT  VERS  2. 2 
NEXT  PC 
010C  0000 
-LI  007  10B 


0100 

LX  I 

H, 0000 

0 1 03 

MVI 

C,  IF 

0105 

CALL 

0005 

0108 

NOP 

0109 

010C 

JMP 

0109 

-G100, 109 

+0109 

-X 

C0Z 1M0E1 10 

A-7E 

B-7400 

D-0000 

H-747E 

S-0100 

P-0109 

JMP 

0109 

-G100, 100 
+0  1  00 
-T0C 

C0Z1M0E1 10 

A-7E 

B— 7400 

D-0000 

H-747E 

S-0100 

P-0100 

LX  I 

Hr  0000 

C0Z1M0E1 10 

A-7E 

B-7400 

D-0000 

H-0000 

S-0100 

P-0103 

MVI 

C,  IF 

C0Z1M0E1 10 

A-7E 

B-74 1 F 

D=0000 

H-0000 

S-0100 

P-0105 

CALL 

0005 

C0Z1M0E1I0 

A— 7E 

B-741F 

D— 0000 

H-0000 

S-00FE 

P-0005 

JMP 

5500 

C0Z 1M0E1 10 

A-7E 

B-74 1 F 

0=0000 

PI-0000 

S-00FE 

P-5500 

JMP 

5BA2 

C0Z1M0E1 10 

A-7E 

B-74 IF 

D-0000 

H-0000 

S-00FE 

P-5BA2 

XTHL 

C0Z1M0E1 10 

A-7E 

B-74 IF 

D— 0000 

PI-0108 

S-00FE 

P-5BA3 

SHLD 

64 4 A 

C0Z1M0E1 10 

A— 7E 

B-74 IF 

D-0000 

H-0103 

S-00FE 

P-5BAG 

XTHL 

C0Z1M0E1 10 

A-7E 

B-74 IF 

D-0000 

H-0000 

S-00FE 

P-5BA7 

JMP 

6506 

C0Z1M0E1 10 

A-7E 

B-7400 

D-0000 

H-747E 

S-0100 

P-010S 

NOP 

C0Z1M0E1 1.0 

A-7E 

B-74 00 

D-0000 

H-747E 

S-0100 

P-0109 

JMP 

0109 

C0Z 1M0E1 10 

A-7E 

B-74 00 

D-0000 

H-747E 

S-0100 

P-0 1 09 

JMP 

0109+0109 
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“dislribution  system”  that  you  could  use 
in  conjunction  with  your  full-size  system. 

It  doesn’t  matter  which  you  load 
first  if  there  is  sufficient  space  between 
the  systems.  But  if  the  systems  are  nearly 
of  equal  size  (like  24K  and  32K),  you 
might  have  trouble  if  you  load  the 
smaller  one  first.  DDT  moves  itself  to  a 
position  just  below  the  CP/M  system,  so 
if  it  tries  to  put  itself  just  below  a  32K 
system,  it  might  land  on  top  of  the  24K 
system.  If  you  boot  the  bigger  system 
first  (as  I  did  in  the  example)  and  then 
DDT  from  the  smaller  system,  DDT  will 


be  below  the  smaller  system,  so  it  can’t 
interfere  with  the  larger  system. 


They  Said  It  Couldn’t  Be  Done 

The  previous  letters  to  Dr.  Dobb  said 
that  it  is  impossible  to  Trace  in  the  BDOS 
because  it  is  not  reentrant,  so  “attempts 
to  trace  through  BDOS  will  result  in  the 
saved  values  being  overwritten  and  de¬ 
stroyed  by  the  recursive  BDOS  calls 
made  by  the  debugger.  This  tends  to  send 
you  to  a  tight  loop  in  never-ever  land.” 


This  is  true.  But  just  because  something 
is  impossible  doesn’t  mean  that  it  can't 
be  done.  Every  good  stage  magician 
knows  that.  If  you  can  create  the  illusion 
that  it  is  being  done,  that  is  good  enough. 


Procedure3. 

-S10E 


0106  05 

00 

0107  00 

95 

0108  00 

a 

— L100J 10B 

0100 

LX  I 

H, 0000 

0103 

MVI 

C,  IF 

0105 

CALL 

9500 

0108 

NOP 

0109 

010C 

JMP 

0109 

■""01007  100 
+0  1 00 

—  T36 

C0Z 1M0E1 10 

0=7E 

B=7400 

D=0000 

H=747E 

S=0100 

P=0100 

L..XI 

H, 0000 

C0Z1M0E1 10 

A=7E 

B=7400 

D=0000 

H=0000 

8=0100 

P=0103 

MVI 

C,  IF 

C0Z1M0E1I0 

0=7E 

B=741F 

D=0000 

H=0000 

8=0100 

P=0105 

CALL 

9500 

C0Z1M0E1 10 

A=7E 

B=74 1 F 

D=0000 

H=0000 

S=00FE 

P=3500 

JMP 

9BA2 

C0Z1M0E1I0 

A=7E 

B=74 1 F 

0=0000 

H=0000 

S=00FE 

P=9B02 

XTHL 

C0Z 1M0E1 10 

A=7E 

B=741F 

0=0000 

H=010S 

S=00FE 

P=9B03 

SHLD 

0440 

C0Z 1M0E1I0 

A=7E 

B=741F 

0=0000 

H=0 108 

S=00FE 

P=9BA6 

XTHL 

C0Z 1M0E1 10 

0=7E 

B=74 1 F 

0=0000 

H=0000 

S=00FE 

P=9BR7 

JMP 

0508 

C0Z1M0E1I0 

0=7E 

B=741F 

D=0000 

H=0000 

S=00FE 

P=O50G 

JMP 

0511 

C0Z1M0E1I0 

0=7E 

B=741F 

0=0000 

H=0000 

S=00FE 

P=051 1 

XCHG 

C0Z1M0E1 10 

0=7E 

B=74 1 F 

0=0000 

H=0000 

8=00FE 

P=051 2 

SHLD 

084-T 

C0Z 1M0E1 10 

0=7E 

B=741F 

D=0000 

H=0000 

S=00FE 

P=0515 

XCHG 

C0Z1M0E1 10 

A=7E 

B=741F 

0=0000 

H=0000 

S=00FE 

P=051G 

MOV 

0,  E 

C0Z 1M0E1 10 

0=00 

B=741F 

0=0000 

H=0000 

S=00FE 

P=051 7 

STO 

B2D6 

C0Z 1M0E1 10 

0=00 

B=741F 

0=0000 

H=0000 

S=00FE 

P=0510 

LX  I 

H, 0000 

C0Z1M0E1 10 

0=00 

B=741F 

0=0000 

H=0000 

S=00FE 

P=A51D 

SHLD 

0845 

C0Z1M0E1 10 

0=00 

B=74 1 F 

0=0000 

H=0000 

S=00FE 

P=O520 

DAD 

SP 

C0Z 1M0E1 10 

0=00 

B=74 1 F 

D=0000 

H=00FE 

S=00FE 

P=052 1 

SHLD 

A80F 

C0Z 1M0E1 10 

0=00 

B=74 1 F 

0=0000 

H=00FE 

S=00FE 

P=0524 

L.X  I 

SP, BE00 

C0Z 1 M0E 110 

0=00 

B=74 1 F 

0=0000 

H=00FE 

S=BE00 

P=A527 

XRA 

0 

C0Z1M0E1 10 

0=00 

B=741F 

0=0000 

H=00FE 

S=BE00 

P=0528 

STA 

B2E0 

C0Z1M0E1 10 

0=00 

B=74 1 F 

D=0000 

H=00FE 

S=BE00 

P=A52B 

STO 

B2DE 

C0Z 1M0E1 10 

0=00 

B=74 1 F 

0=0000 

H=00FE 

S=BE00 

P=052E 

L.X  I 

H, B274 

C0Z1M0E1 10 

0=00 

B=74 1 F 

D=0000 

H=B274 

S=BE00 

P=A53 1 

PUSH 

H 

C0Z 1M0E1 10 

0=00 

B=74 1 F 

0=0000 

H=B274 

S=BDFE 

P=0532 

MOV 

A,  C 

C0Z1M0E1I0 

0=1F 

B=74 IF 

0=0000 

H=B274 

S=BDFE 

P=A533 

CPI 

29 

C1Z0M1E0I0 

0=1F 

B=741F 

0=0000 

H=B274 

S=BDFE 

P=0535 

RNC 

C1Z0M1E0I0 

0=1F 

B=74 1 F 

0=0000 

H=B274 

8=BDFE 

P=053E 

MOV 

C,  E 

C1Z0MIE0I0 

0=1F 

B=7400 

0=0000 

H=B274 

S=BOFE 

P=0537 

LX  I 

H, 0547 

(Continued  on  top  of  page  65) 
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C1Z0M1E0I0 

0=1F 

B=7400 

D=0000 

H=0547 

S=BDFE 

P=R530 

MOV 

E,  0 

C1Z0M1E0I0 

0=1F 

B=7400 

D=001F 

H=0547 

B=BDFE 

P=053B 

MV  I 

Di  00 

Cl Z0M1E0I0 

0=1F 

B=7400 

D=001F 

H=0547 

S=BDFE 

P=053D 

DOD 

D 

C0Z0M1E0I0 

0=1F 

B=7400 

D=001F 

H=056E 

S=BDFE 

P=053E 

DOD 

D 

C0Z0M1E0I0 

0=1F 

B=7400 

D=00 1 F 

H=05S5 

S=BDFE 

P=053F 

MOV 

E,  M 

C0Z0M1E0I0 

0=1F 

B=7400 

D=00k;E 

H=05S5 

S=BDFE 

P=O540 

I  NX 

H 

C0Z0M1E0I0 

0=1F 

B=7400 

D=002E 

H=05SE 

S=BDFE 

P=054 1 

MOV 

D,  M 

C0Z0M1E0I 0 

0=1F 

B=7400 

D=B22E 

H=05S6 

S=BDFE 

P=0542 

LHLD 

0S43 

C0Z0M1E0I0 

0=1F 

B=7400 

D=B226 

H=0000 

S=BDFE 

P=0545 

XCHG 

C0Z0M1E0I0 

0=1F 

B=7400 

D=0000 

H=B22E 

S=BDFE 

P=0546 

PCHL 

C0Z0M1E0I0 

0=1F 

B=7400 

D=0000 

H=B22E 

S=BDFE 

P=B22S 

LHLD 

B2BB 

C0Z0M1E0I0 

o=if 

B=7400 

D=0000 

H=B47E 

S=BDFE 

P=B229 

SHLD 

0345 

C0Z0M1E0I0 

0=1F 

B=7400 

D=0000 

H=B47E 

S=BDFE 

P=B22C 

RET 

C0Z0M1E0I0 

0=  IF 

B=7400 

D=0000 

H=B47E 

S=BE00 

P=B274 

L.DO 

B2DE 

C0Z0M1E0I0 

0=00 

B=7400 

D=0000 

H=B47E 

S=BE00 

P=B277 

ORO 

0 

C0Z1M0E1 10 

0=00 

B=7400 

D=0000 

H=B47E 

S=BE00 

P=B27S 

JZ 

B291 

C0Z1M0E1 10 

0=00 

B=7400 

D=0000 

H=B47E 

S=BE00 

P=B291 

LHLD 

OS0F 

C0Z 1M0E1 10 

0=00 

B=7400 

D=0000 

H=00FE 

S=BE00 

P=B294 

BPHL 

C0Z1M0E1I0 

0=00 

B=7400 

D=0000 

H=00FE 

S=00FE 

P=B295 

LHLD 

0S45 

C0Z1M0E1I0 

0=00 

B=7400 

D=0000 

H=B47E 

S=00FE 

P=B298 

MOV 

0,  L 

C0Z1M0E1 10 

0=7E 

B=7400 

D=0000 

H=B47E 

S=00FE 

P=B299 

MOV 

B,  H 

C0Z1M0E1 10 

0=7E 

B=B400 

D=0000 

H=B47E 

S=00FE 

P=B290 

RET 

C0Z1M0E1 10 

0=7E 

B=B400 

D=0000 

H=B47E 

B=0100 

P=010S 

NOP 

C0Z1M0E1I0 

fl=7E 

B=B400 

D=0000 

H=B47E 

S=0100 

P=0109 

JMP 

0109 

C0Z1M0E1 1.0 
~G0 

0=7E 

B=B400 

D=0000 

H=B47E 

S=0100 

P=0109 

JMP 

0109+0109 
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Julian  Dates  for 
Microcomputers 


Julian  dates  have  long  been  used  by 
astronomers  to  facilitate  accurate 
reckoning  of  dates  over  long  periods 
of  time,  and  they  can  also  be  extremely 
useful  in  various  applications  of  comput¬ 
ers.  A  Julian  date  is  simply  the  number  of 
a  given  day  counted  in  sequence  from 
some  base  date  which  is  assigned  Julian 
date  0.  For  example,  if  1  January  1983  is 
taken  as  the  base  date  0,  then  2  January 
1983  would  have  Julian  date  1,  3  January 
1983  would  have  Julian  date  2,  and  1  Jan¬ 
uary  1984  would  have  Julian  date  365. 

There  are  at  least  four  reasons  why 
Julian  dates  can  be  usefully  applied  in 
computer  programs  (inventive  comput- 
erists  can  probably  find  more): 

(1)  The  Julian  date  provides  a  com¬ 
pact  and  economical  way  of  storing  a 
date  as  opposed  to  representing  it  as  a 
string  of  ASCII  characters. 

(2)  Any  two  dates  may  be  simply 
compared  by  an  arithmetic  test  to  deter¬ 
mine  which  date  is  earlier.  This  is  espe¬ 
cially  useful  when  items  are  to  be  sorted 
by  date. 

(3)  The  exact  number  of  days  be¬ 
tween  any  two  dates  can  be  determined 
by  a  simple  subtraction. 

(4)  When  a  Julian  date  is  divided  by 
7,  the  remainder  gives  the  corresponding 
day  of  the  week  (this  will  be  explained  in 
more  detail  below). 

True  Julian  dates  as  used  by  astrono¬ 
mers  take  noon,  1  January  4713  B.C.  as 
the  base  date  (astronomers  count  days 
from  noon  to  noon).  But  fqr  most  com¬ 
puter  work,  it’s  more  useful  to  take  a 
year  someplace  in  the  current  century  as 
a  base  year,  because  there  normally  is  no 
need  to  reference  dates  very  far  back  in 
the  past.  A  base  date  in  1900,  for  example, 
would  be  sufficient  for  the  Julian  date 
representation  of  employee  birth  dates  in 
almost  any  business  today.  Furthermore, 
restricting  the  forward  span  of  dates  from 
the  base  date  to  some  reasonable  future 
limit  allows  the  Julian  date  to  be  stored 
and  manipulated  economically.  For  exam¬ 
ple,  choosing  to  store  a  Julian  date  in  a 
16-bit  word  (two  bytes)  allows  a  span  of 
65,536  days,  which  is  approximately 
179.4  years.  The  algorithms  for  Julian 


by  Gordon  King 


Gordon  King,  King  Software,  P.O.  Box 
208,  Red  Bank,  New  Jersey  07701. 


date  conversion  given  below,  which  use  a 
16 -bit  Julian  date,  allow  a  base  year  to  be 
chosen  between  1900  and  1920,  thus 
giving  a  terminating  date  between  2079 
and  2099  in  the  next  century. 

In  order  to  use  Julian  dates  on  a 
computer,  two  conversion  routines  are 
needed:  CTOJ,  which  converts  a  calendar 
date  to  a  Julian  date,  and  JTOC,  which 
converts  a  Julian  date  back  to  a  calendar 
date.  The  routines  given  here  are  based  on 
Algorithm  199  in  The  Collected  Algo¬ 
rithms  of  the  ACM,  as  presented  by  R.  G. 
Tantzen  in  1963.  Calendar  dates  are 
given  in  the  form  DAY  (an  integer  from  1 
to  31),  MONTH  (an  integer  from  1  to  12), 
and  YEAR  (an  integer  from  1900  to 
2099).  The  Julian  date  is  given  (or  re¬ 
turned)  as  the  16-bit  unsigned  integer 
JDATE,  ranging  from  0  (Julian  date  0) 
to  65,535  (last  day). 

The  base  date  is  1  March  1900,  or 
1  March  of  any  leap  year  after  1900  not 
greater  than  1920.  The  first  of  March 
rather  than  the  first  of  January  is  used  as 
a  base  date  in  order  to  avoid  problems 
with  29  February  in  leap  years.  For  simi¬ 
lar  reasons,  the  routines  as  given  will  not 
work  for  dates  before  1900  or  after  2099 
(1900  and  2100  are  not  leap  years,  while 
2000  is).  Readers  interested  in  represent¬ 
ing  dates  outside  these  ranges  should  refer 


to  Tantzen’s  original  algorithms,  which 
handle  any  Gregorian  calendar  date  (but 
not  within  16  bits). 

The  conversion  routines  are  shown 
first  in  a  pseudo  higher-level  language 
to  make  the  algorithms  clear  (see  Figure 
1,  below).  But  the  reader  should  be 
cautioned  that  they  cannot  be  directly 
translated  into  any  higher-level  language 
which,  like  many  BASICs,  doesn’t  sup¬ 
port  long  (32-bit)  integer  arithmetic. 
Though  the  results  are  all  16-bit  quanti¬ 
ties  (or  less),  some  of  the  intermediate 
calculation  requires  32-bit  arithmetic, 
and  the  algorithms  also  depend  on  the 
properties  of  integer  division. 

As  illustrated  in  Figure  1,  the  normal 
month  number  is  converted  to  the  num¬ 
ber  of  a  month  in  a  pseudo  year  run¬ 
ning  from  1  March  through  28  (or  29) 
February,  and  the  year  number  is  adjusted 
if  necessary.  The  magic  number  1461 
which  appears  in  CTOJ  is  simply  the 
number  of  days  in  a  leap-year  cycle  of 
three  years  of  365  days  each  and  one  year 
of  366  days.  Therefore  the  expression 
(1461  *  y )/ 4  gives  the  total  number  of 
days  in  all  preceding  years  from  the  base 
year  up  to  the  specified  year.  The  integer 
function  (153*m  +  2)/5  similarly  gives 
the  total  number  of  days  in  any  pseudo 
year  up  to,  but  not  including,  month  m. 
Therefore,  adding  DAY  to  the  sum  of  the 


Conversion  of  Calendar  Date  to  Julian  Date 

CTOJ:  y  =  YEAR  -  Base  Year 

If  MONTH  ,gt.  2,  m  =  MONTH  -  3 

else  m  =  MONTH  +  9,  y  =  y  -  1 
JDATE  =  (1461  *y)/4  +  (153*m  +  2 ) / 5  +  DAY  -  1 


Conversion  of  Julian  Date  to  Calendar  Date 

JTOC:  y  =  (4  *  JDATE  +  3 )/ 146 1 

d  =  (4  *  JDATE  +  3)  mod  1461 

YEAR  =  y  +  Base  Year 

d  =  d/4+1 

m  =  (5  *d  -  3)/  153 

d  =  (5*d-3)modl53 

DAY  =  d/5  +  1 

If  m  .It.  10,  MONTH  =  m  +  3 

else  MONTH  =  m  -  9,  YEAR  =  YEAR  +  1 

Figure  1. 
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two  preceding  expressions  gives  the  day 
number  of  the  specified  calendar  date; 
and  finally  subtracting  1  gives  the  base- 
zero  Julian  date.  The  routine  JTOC  sim¬ 
ply  reverses  the  above  calculation  to  con¬ 
vert  back  to  calendar  date. 

The  JDATE  numbers  used  by  these 
algorithms  may  also  be  converted  to  day 
numbers  in  other  similar  date  systems  by 
the  addition  or  subtraction  of  a  suitable 
conversion  constant.  Suppose  that  FDATE 
is  such  a  day  number  in  some  “foreign” 
date  system  which  also  numbers  days 
sequentially,  but  from  a  different  base 
date.  Then 

JDATE  =  FDATE  +  CC 
and 

FDATE  =  JDATE  -  CC 

where  CC  is  the  conversion  constant, 
which  is  simply  the  JDATE  value  for  the 
base  date  of  the  foreign  system;  it  must  of 
course  lie  within  the  valid  JDATE  range. 
For  example,  MP/M  and  CP/M  Plus  use  a 
16-bit  integer  date  with  1  January  1978 
taken  as  Day  1  (hence  31  December  1977 
is  Day  0).  The  JDATE  value  for  31  De¬ 
cember  1977  is  28,429  if  1900  is  used  as 
the  JDATE  base  year,  or  21,124  for  base 
year  1920.  Therefore  simply  adding  the 
appropriate  one  of  these  two  constants 
to  MP/M’s  date  at  the  beginning  of  the 
routine  JTOC  converts  it  to  the  corre¬ 
sponding  JDATE  and  results  in  the  cor¬ 
rect  calendar  date.  Conversely,  subtracting 
it  from  JDATE  at  the  end  of  the  routine 
CTOJ  gives  back  the  MP/M-form  date 
corresponding  to  the  given  calendar  date 
(calendar  dates  before  31  December  1977 
will  result  in  negative  MP/M  dates,  which 
may  have  some  useful  interpretation  out¬ 
side  of  MP/M  itself). 

Before  going  on  to  present  the  two 
routines  in  Z80  assembly  language,  men¬ 
tion  should  be  made  of  the  method  of 
determining  the  day  of  the  week  corre¬ 
sponding  to  a  given  Julian  date.  When  a 
Julian  date  is  divided  by  7,  the  remainder 
will  be  one  of  the  seven  numbers  from  0 
to  6  (the  quotient  is  ignored).  These 
correspond  to  the  seven  days  of  the  week 
in  order,  beginning  from  a  day  which 
depends  on  the  base  year.  For  base  year 
1900.  a  remainder  of  0  means  Thursday, 
1  means  Friday,  and  so  on  down  to  6, 
which  means  Wednesday.  For  base  year 
1920,  a  remainder  of  0  means  Monday,  1 
means  Tuesday,  etc.  Consequently,  these 
remainders  can  be  used  to  index  into  a 
suitably  ordered  table  of  day  names  when 
it’s  required  to  print  the  day  of  the  week 
corresponding  to  a  given  date  (after  it’s 
been  converted  to  a  Julian  date,  of 
course). 

Finally,  the  listing  (page  68)  provides 
the  two  conversion  subroutines  in  Z80 
assembly  language.  The  date  is  transferred 
in  the  byte  DAY,  the  byte  MONTH,  and 


the  word  (two  bytes)  YEAR,  while  the 
Julian  date  is  transferred  in  the  word 
JDATE.  Since  the  Julian  date  is  con¬ 
tained  in  a  16 -bit  word,  the  legal  range 
of  dates  is  from  1  March  1900  to  4  August 
2079  if  1900  is  chosen  as  the  base  year,  or 
from  1  March  1920  to  4  August  2099  if 
1920  is  chosen  as  the  base. 

The  subroutine  CTOJ  checks  DAY, 
MONTH,  and  YEAR  for  legal  values  and 
jumps  to  a  routine  ERROR  (not  supplied) 
in  case  they’re  out  of  range.  Two  sub¬ 
routines  are  also  supplied  for  integer 
multiplication  and  division,  but  if  date 
conversions  are  to  be  done  heavily,  as  in 
an  inner  loop,  some  improvement  in  per¬ 
formance  could  be  gained  by  using  shifts 
and/or  adds  to  do  the  multiplications  by 
4  and  5  and  the  divisions  by  4.  j 
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Julian  Dates  (Text  begins  on  page  66) 

YEAR0  =  1900  ; BASE  YEAR 

; CONVERT  CALENDAR  DATE  TO  JULIAN 


CTO J :  LD 

LD 
OR 
JP 
CP 
JP 
SUB 
JR 
ADD 
DEC 

CTO J 1 :  LD 
LD 
LD 
ADD 
LD 
OR 
JP 
LD 
CP 
JP 

PUSH 

LD 

CALL 

LD 

CALL 

POP 

PUSH 

LD 

CALL 

INC 

INC 

LD 

CALL 

POP 


HL , ( YEAR ) 
A, (MONTH) 
A,  A 

Z , ERROR 
A,  12  +  1 
NC , ERROR 
A,  3 

NC , CTO J 1 
A,  12 
HL 
E,  A 
D  ,  0 

BC , -YEAR0 
HL  ,  BC 
A  ,  H 
A,  A 

NZ , ERROR 
A,  L 

A,  179+1 
NC , ERROR 
DE 

DE, 1461 

MULWV 

BC  ,  4 

DIVLW 

HL 

DE 

DE, 153 
MULWV 
HL 
HL 

BC  ,  5 

DIVLW 

HL 


ADD  HL , DE 

JP  C, ERROR 

LD  A, (DAY) 

DEC  A 


CP  A, 31 


GET  THE  YEAR 

AND  THE  MONTH 

CHECK  FOR  A  LEGAL  VALUE 


;  MONTH  IN  MAR-FEB  "YEAR" 

;  JAN  OR  FEB  BECOME  10,  11 

;  OF  PREVIOUS  YEAR 
;  PUT  MONTH  IN  DE 

;  SUBTRACT  THE  BASE  YEAR 

;  CHECK  FOR  LEGAL  YEAR 


;  SAVE  THE  MONTH 
;  DAYS  IN  A  LEAP-YEAR  CYCLE 
;  DE*HL  TO  ( DE , HL ) 

;  ( DE , HL ) / BC  TO  DE  (QUOTIENT) 

;  GET  THE  MONTH  BACK 
;  SAVE  ( YEAR  *  1 4  6 1 ) / 4 

;  DE*HL  TO  ( DE , HL ) 

;  ADD  2 

;  (NO  OVERFLOW  POSSIBLE) 

;  ( DE , HL ) / BC  TO  DE  (OUOTIENT) 

;  GET  BACK  FIRST  TERM 
;  ADD  ( 1S3*M0NTH  +  2) /5 
,  ERROR  IF  OVERFLOW 
;  GET  DAY 

; REDUCE  BY  ONE  FOR  BASE-0  J.D 
;  CHECK  FOR  LEGAL  VALUE 

(Continued  on  next  page) 
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Julian  Dates  (Listing  continued,  text  begins  on  page  66) 


JP 

NC , ERROR 

LD 

E,  A 

;  TO  DE 

LD 

D,  0 

ADD 

HL  ,  DE 

; ADD  IN 

JP 

C , ERROR 

; ERROR  IF  OVERFLOW 

LD 

RET 

( JDATE) , HL 

; STORE  AWAY 

CONVERT  JULIAN  DATE  BACK  TO  CALENDAR  DATE 


JTOC  : 


JTOC1 


JTOC  2 


JTOC  3 


LD 

HL , ( JDATE ) 

GET  THE  JULIAN 

LD 

DE  ,  4 

4* JDATE  +  3 

CALL 

MULWW 

DE*HL  TO  (DE, 

LD 

BC  ,  3 

ADD 

HL  ,  BC 

JR 

NC , JTOC 1 

INC 

DE 

LD 

BC  ,  1461 

y  =  (4* JDATE  + 

CALL 

DIVLW 

(DE,HL) /BC  TO 

PUSH 

DE 

SAVE  y,  HL  HAS 

LD 

BC  ,  4 

d  =  d/4  +  1 

LD 

DE  ,  0 

CALL 

DIVLW 

(DE,HL) /BC  TO 

INC 

DE 

LD 

HL  ,  5 

5  *  d  -  3 

CALL 

MULWW 

DE*HL  TO  (DE, 

LD 

BC  ,  3 

OR 

A,  A 

SBC 

HL  ,  BC 

JR 

NC , JTOC  2 

DEC 

DE 

LD 

BC ,  153 

m  =  ( 5*d  -  3 ) / 

CALL 

DIVLW 

(DE,HL) /BC  TO 

PUSH 

DE 

SAVE  m,  HL  HAS 

LD 

BC  ,  5 

DAY  =  d/5  +  1 

LD 

DE  ,  0 

CALL 

DIVLW 

(DE,HL) /BC  TO 

INC 

DE 

LD 

A  ,  E 

LD 

(DAY)  ,  A 

POP 

HL 

m 

POP 

DE 

y 

LD 

A,  L 

MONTH  =  m  +  3 

ADD 

A,  3 

CP 

A, 12+1 

IF  MONTH  . GT . 

JR 

C , JTOC  3 

SUB 

A  ,  1  2 

MONTH  =  MO 

INC 

DE 

y  =  y  +  1 

LD 

(MONTH) , A 

LD 

HL , YEAR0 

YEAR  =  y  +  Bas 

ADD 

HL  ,  DE 

LD 

RET 

(YEAR) , HL 
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;  MULTI  PLY  HL*DE,  RETURN  32-BIT  PRODUCT  IN  DE  (HIGH)  AND  HL  (LOW) 


MULWW : 

LD 

B  ,  H 

LD 

C  ,  L 

LD 

HL  ,  0 

LD 

A,  16 

MULWW1 : 

ADD 

HL  ,HL 

EX 

DE  ,HL 

ADC 

HL  ,HL 

EX 

DE  ,  HL 

JR 

NC , MULWW 2 

ADD 

HL  ,  BC 

JR 

NC , MULWW2 

INC 

DE 

MULWW 2 : 

DEC 

A 

JR 

RET 

NZ ,MULWW1 

; DIVIDE 

( DE , HL ) 

BY  BC .  QUOTI 

DIVLW : 

EX 

DE  ,HL 

LD 

A,  16 

DIVLW1 : 

EX 

DE  ,  HL 

ADD 

HL  ,  HL 

EX 

DE ,  HL 

ADC 

HL  ,  HL 

SBC 

HL  ,  BC 

JR 

NC , DIVLW3 

ADD 

HL  ,  BC 

DIVLW2 : 

DEC 

A 

JR 

RET 

NZ  ,  DIVLW1 

DIVLW3 : 

INC 

DE 

JR 

DIVLW2 

;  MU  LTI PL  I CAND  TO  BC 

;  INITIALIZE  PRODUCT 
;  COUNT  16-BIT  MULTIPLIER 
;  SHI  FT  DE , HL  LEFT  ONE 


JUMP  IF  NO  MULTIPLIER  BIT 
ELSE  ADD  MULTIPLICAND  TO  RESULT 
IF  LOW  ORDER  WORD  OVERFLOWS, 
CARRY  INTO  HIGH  ORDER 
CONTINUE  FOR  16  BITS 


TO  DE,  REMAINDER  TO  HL . 


HIGH  ORDER  TO  HL ,  LOW  TO  DE 
COUNT  16-BIT  QUOTIENT 
SHIFT  ONE  BIT  FROM  DE  TO  HL 


;WILL  DIVISOR  GO  IN  YET? 

; NO  -  RESTORE  HL 
;  CONTINUE  FOR  16  BITS 


;  INCREMENT  QUOTIENT 
;  LEAVE  RESIDUE  IN  HL ,  CONTINUE 


End  Listing 
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16  BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


8088  Addressing  Modes 

The  short  comment  on  8088  Base 
Relative  Indexed  Stack  addressing  and 
the  table  from  Leo  Scanlon’s  book, 
printed  in  this  column  a  few  months  ago, 
drew  a  surprising  number  of  letters. 
Albert  Brunelli,  of  N.  Chelmsford,  Mass., 
practically  wrote  a  whole  tutorial;  I 
found  it  so  helpful  that  I  am  reprinting  it 
verbatim  below. 

“I  am  writing  in  response  to  the  16- 
Bit  Software  Toolbox  column  of  March 
1983.  The  primary  purpose  of  this  letter 
is  to  explain  some  of  the  uses  of  the 
8086/88’s  BP  register.  First  I  will  com¬ 
ment  on  Leo  Scanlon’s  listing  on  page  17 
of  the  March  1983  issue. 

“The  subroutine  will  prove  only  that 
the  DS  register  is  not  the  default  segment 
for  BP- based  memory  references.  The 
ASSUME  statement  does  not  change  any 
register.  It  is  merely  a  means  of  assuring 
the  assembler  that  you  know  what  you 
are  doing  when  you  make  an  anonymous 
reference  (use  a  base  or  index  as  an  offset 
without  specifying  a  segment  register). 
Mr.  Scanlon  appears  to  understand  this 
when  he  initializes  the  DS  register.  How¬ 
ever,  he  never  initializes  the  SS  register  to 
the  segment  STACK  which  he  would  have 
to  do  to  prove  his  case.  If  he  were  to 
change  the  SS  to  STACK,  and  if  it  weren’t 
already  pointing  at  STACK  of  course,  he 
could  never  return  from  the  subroutine. 
If  the  DL  and  DH  registers  hold  OFFh  at 
the  end  of  the  routine,  it  is  merely  a  co¬ 
incidence.  He  would  do  better  to  push 
the  data  onto  the  stack  and  then  retrieve  it 
using  the  BP  register.  This  technique  will 
become  clearer  as  we  get  further  along. 

“To  get  a  good  feel  for  the  intended 
use  of  the  BP  register,  one  must  under¬ 
stand  the  philosophy  behind  the  use  of 
the  8086  instruction  set.  As  I  understand 
it,  Intel  wanted  to  create  a  microprocessor 
with  an  instruction  set  which  lent  itself 
well  to  the  implementation  of  high-level 
languages,  specifically  to  Intel’s  systems 
language,  PL/M. 

“In  PL/M  and  most  other  structured 
languages,  most  arguments  are  passed  to 
procedures  (functions,  subroutines)  on 
the  stack.  However,  since  the  return 
address  will  be  the  lowest  address  on  the 
stack,  considerable  manipulation  must  be 
done  to  access  the  arguments  while  main¬ 
taining  the  return  address.  Intel  added 
two  nice  features  to  the  instruction  set  to 
make  argument  retrieval  easier.  The  BP 
register  is  one  of  these. 

“Let’s  assume  we  wish  to  pass  two 


arguments  to  the  FAR  subroutine  SUB1 . 
We  might  pass  them  as  shown  below: 

PUSH  CX 
PUSH  DX 
CALL  SUB1 


“After  the  CALL  instruction  is  executed, 
the  stack  will  look  like  this: 

low  address  OLD  IP  offset 
OLD  CS  segment 
ARG2  from  DX 

high  address  ARG1  from  CX 


“To  retrieve  the  arguments  and  return 
properly,  SUB1  might  follow  the  proce¬ 
dure: 

SUB1  PROC  FAR 
PUSH  BP 
MOV  BP,SP 

PUSH  DS  ;  save  registers 
PUSH  SI 
PUSH  AX 

.  ;body  of  subroutine 


DONE:  POP  AX 
POP  SI 
POP  DS 
POP  BP 
RET  4 
SUB1  ENDP 


“Moving  SP  to  BP  will  allow  us  to  index 
into  the  arguments  passed  on  the  stack 
using  BP.  The  contents  of  the  stack  when 
we  get  to  the  body  of  SUB1  are  shown 
as  follows: 


low  address 

OLD  AX 

;“top”  of  stack 

OLD  SI 
OLD  DS 
OLD  BP 

;BP  points  here 

OLD  IP 

;BP+2 

OLDCS 

;BP+4 

ARG2 

;BP+6 

high  address 

ARG1 

;BP+8 

“We  may  thus  retrieve  the  arguments  with 
the  instructions: 

MOV  AX,[BP+6] 

;  fetch  ARG2 
MOV  SI,[BP+8] 

;  fetch  ARG1 

“Any  reference  using  BP  as  a  base 
will  assume  that  it  is  in  reference  to  the 
stack  segment  (with  or  without  an 
ASSUME  declaration). 

“Now  we  have  fetched  the  arguments 
without  disturbing  the  return  address. 
How  will  we  clean  up  the  stack  so  that 
the  arguments  will  not  clutter  it  up  for¬ 
ever?  Once  again  Intel  comes  to  the  rescue 
with  the  ‘RET  n’  instruction.  The  ‘n’  part 
of  the  instruction  tells  the  processor  how 
many  bytes  to  discard  from  the  stack 
after  it  has  taken  off  the  return  address. 
In  other  words,  it  will  add  ‘n’  to  the  stack 
pointer  (SP)  after  fetching  the  return 
address. 

“The  final  use  to  which  I  will  put  the 
BP  register  is  one  which  I  have  found  very 
helpful  in  memory-test  programs  which 
do  not  have  access  to  the,  as  yet  unveri¬ 
fied,  stack  area  of  RAM.  We  may  create 
synthetic  subroutines  which  may  be 


LEA 

BX,TABLE_1 

;point  to  ROM  table 

MOV 

CX,NUM —ENTRIES 

;number  of  table  entries 

LEA 

BP, CONTI 

;BP  becomes  return  addr 

JMP 

SYN—SUB1 

CONTI: 

jcontrol  returns  here 

SYN_SUB  1 ; 

jsynthetic  subroutine 

JMP 

BP 

;pseudo-return  instr. 

Figure  1 . 
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‘called’  from  anywhere  within  the  same 
code  segment.  The  idea  is  that  the  return 
address  is  placed  in  a  register  before 
jumping  to  the  subroutine,  which  termi¬ 
nates  with  a  jump  register  instruction 
such  as  shown  in  Figure  1,  page  72. 

“The  LEA  BP  instruction  will  place 
the  offset  of  the  CONTI  label  in  the  BP 
register.  The  BP  register  is  the  perfect  one 
to  use  in  a  situation  like  this  because  we 
have  no  stack  to  which.it  may  point.  The 
JMP  BP  instruction  may  be  thought  of  as 
roughly  equivalent  to  the  8080’s  PCHL 
instruction,  although  it  is  more  powerful 
since  any  general  register  may  be  used  as 
the  source.” 


Wishful  Thinking  Dept. 

Jim  Howell  wrote  to  point  out  a 
truly  glaring  error,  found  on  page  3-13  of 
the  iAPX-88  Book  (July  1981  edition), 
which  readers  of  this  column  may  find 
amusing  or  amazing.  “16-bit  operands 
are  stored  in  memory  with  the  most  sig¬ 
nificant  byte  (MSB)  first,  followed  by  the 
least  significant  byte  (LSB)  in  the  next 
location.”  The  picture  set  at  the  bottom 
of  the  page  in  the  book  repeats  this 
error. 

8088  Line  Generator 

Dan  Rollins  of  Glendale,  Calif,  sent 
in  an  8088  assembler  version  of  the  fast- 
vector  algorithm  featured  in  Dave  Cortesi’s 
column  of  December  1982  and  February 
1983.  His  comments  follow: 

“The  routine  is  self- modifying  and 
needs  no  external  storage  area.  The  code 
that  calculates  the  coordinate  pairs  is 
blazing  fast.  It’s  a  shame  that  the  BIOS 
write-dot  routine  (which  it  calls)  is  so 
slow.  I  am  using  a  version  of  this  routine 
in  an  arcade  game  I  am  currently  writing. 
All  of  the  drawing  and  point  testing  in 
that  game  takes  place  in  a  buffer  and  I 
use  a  much  faster  PLOTDOT  routine.” 

Listing  1  (page  75)  contains  the 
line  generation  subroutine  proper,  while 
Listing  2  (page  77)  demonstrates  how  to 
call  the  subroutine  from  BASIC. 


PC -TALK  III 

Andrew  Fluegelman,  author  of  the 
excellent  PC-TALK  communications  pro¬ 
gram  and  originator  of  the  “Freeware” 
concept,  has  announced  a  new  version 
that  has  some  significant  enhancements. 
Version  III  has  been  rewritten  so  that  all 
features  operate  at  1200  baud.  The  Key 
Directory  has  been  expanded  to  40  per¬ 
manent  strings,  and  the  Dialing  Directory 
now  holds  60  entries  and  stores  selective 
character  stripping  for  each  entry. 

The  Transmit  and  Receive  routines 
now  offer  the  options  of  line-paced  trans¬ 


mission,  sending  of  binary  files,  and  the 
XMODEM  error  checking  protocol.  Pro¬ 
gram  defaults  can  be  reset  interactively 
while  the  program  is  running.  Other  new 
bells  and  whistles  include  auto-redial, 
margin  width  alarm,  and  a  screen  dump 
to  disk. 

Updates  to  Version  III  for  previous 
PC-TALK  owners  are  only  $10.00,  while 
the  suggested  donation  for  new  owners  is 
$35.00.  As  before,  everyone  is  encouraged 
to  make  copies  of  the  program  and  dis¬ 
tribute  them  as  widely  as  possible  for 
free;  recipients  of  such  copies  are  re¬ 
quested  to  mail  in  a  donation  if  they 
appreciate  the  program  and  want  to 
promote  the  development  of  more  Free¬ 
ware.  PC-TALK  is  available  from  The 
Headlands  Press,  P.O.  Box  862,  Tiburon, 
California  94920. 

(Listings  begin  on  page  75) 
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The  Line  Generator  Subroutine 

Listing  One  (Text  begins  on  page  72) 


PBde  ,132 

title  DRAWLINE .ASM  Dsn  Rollins 

public  drawline 

58088  self-modifying  program  implements  fsst-vector  algorithm 
5  described  by  MichalsKy,  DDJ  #74,  12/82 
5  see  slsot  FAST-LINE  DRAWING  TECHNIQUE.  BYTE,  Aug  81 

5 routine  expects  to  be  called  from  BASIC  vis! 

5  CALL  BRAWL INE(  VZ(  0  ) ) 

5  where  VZ( 0 )  =  XI  starting  elm  (0-319) 

5  V%( 1 )  =  Y1  starting  row  (0-159) 

5  m  2)  =  X2  ending  elm 

5  VZ( 3)  =  Y2  ending  row 

5  VX(4)  =  color  (0,1, 2, 3) 

5  V7.(5)  =  length 

5  0  =  drsu  entire  line 

5  else  =  draw  sub-  or  super-set  of  this  vector 

code  group  cseg 

0000  cseg  segment  public  'code' 

assume  CS!cseg,  DStnothing,  ESInothing 

5  maKe  it  easier  to  access  variables  and  arguments 


— 

ARGl 

eou 

word 

ptr 

CBP+63 

s 

XI 

eou 

word 

ptr 

Csi  3 

= 

Y1 

eou 

word 

ptr 

Csi+23 

r 

X2 

eou 

word 

ptr 

Csi+43 

= 

Y2 

eou 

word 

ptr 

Csi+63 

= 

COLOR 

eou 

byte 

ptr 

Csi +8 3 

= 

LEN 

eou 

word 

ptr 

Csi+103 

5  these  are  values  that  will  be  inserted  in  the  code 


=  0041 

INC.X 

eou 

41H 

=  0049 

DEC_X 

eou 

49H 

=  0042 

INC_Y 

eou 

42H 

=  004A 

DEC_Y 

eou 

4AH 

5  these  are  the  addresses  where  new  code  is  overlayed 


ADJ_LONG_AXIS 

eou 

byte  ptr  cs!Cdi3 

= 

AD.J.HASTER 

eou 

word  ptr  cstCdi+33 

= 

TEST.MASTER 

eou 

word  ptr  cstCdi+73 

= 

ALT_ADJ_MASTER 

eou 

word  ptr  cs!Cdi+133 

ADJ_SHRT_AXIS 

eou 

byte  ptr  cs!Cdi+153 

page 

oooo 

drawline  proc 

far 

oooo 

55 

push 

bp 

5 always  save 

0001 

8B  EC 

mov 

bp.sp 

0003 

8B  76  06 

BOV 

si, ARGl  5 si  =>  address 

5 ie,  VZ(0> 
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0006 

B3 

41 

RiOV 

blrlNC.X 

} assume  Xsiep  =  +1 

0008 

8B 

44  04 

BOV 

axrX2 

OOOB 

2B 

04 

sub 

axrXl 

OOOD 

7D 

04 

jge 

dll 

»if  XI  <=  X2  then  no  change 

OOOF 

B3 

49 

mov 

blfDEC.X 

fXstep  =  -1 

001 1 

F7 

D8 

neg 

s>; 

i Xdist  =  abs<  Xdist) 

0013 

dill 

0013 

8B 

C8 

so  V 

cxrax 

»s3ve  Xdist 

0015 

B7 

42 

BOV 

bh.INC-Y 

» assume  Ystep  =  +1 

0017 

8B 

44  06 

BOV 

ax»  Y2 

001 A 

2B 

44  02 

sub 

ax»Yl 

001D 

7D 

04 

jge 

dl2 

rif  Y1  <=  Y2  then  no  change 

001F 

B7 

4A 

mov 

bhrBEC.Y 

» Ystep  =  -1 

0021 

F7 

D8 

neg 

3>: 

r Ydist  =  abs(Ydist) 

0023 

dl2! 

0023 

8B 

DO 

BOV 

dxrax 

Jsave  Ydist 

0025 

BF 

005D  R 

BOV 

diroffset  cs!Bodify_base  rpoint  to  the  code 

{  to  Bodify 

0028 

3B 

B1 

CBP 

dx»cx 

rdetermine  longest  axis 

002A 

7D 

04 

jge 

dl3 

*Y  is  longem  so  skip 

002C 

87 

CA 

xchg 

cxrdx 

{swap  Xdistf  Ydist 

0O2E 

86 

DF 

xchg 

blrbh 

1  swap  INC/DEC  X/Y  values 

0030 

dl3t 

{modify! 

0030 

2E! 

88  3D 

BOV 

ADJ.LOMG 

_AXISrbh  ?  the  1st  INC/DEC  code 

0033 

2Et 

89  4D  03 

mov 

ADJ_MASTERr ex  r  main  duly  Baster  adjustment 

0037 

D1 

E? 

shr 

cxrl 

!set  up  cycle  tester 

003? 

2e: 

8?  4D  07 

BOV 

TEST_MASTERr cx  i  lest  for  cycling 

003D 

2e: 

8?  55  OD 

BOV 

ALT-ADJ. 

HASTERrdx  5  alternate  adjustment 

0041 

2e: 

88  5D  OF 

BOV 

ADJ-SHRT 

.AXIS.bl  5  alternate  INC/DEC  code 

0045 

8B 

FA 

BOV 

di  rdx 

!DI  is  counter!  long  axis  length 

0047 

83 

7C  OA  OO 

CBP 

LEW»0 

rif  length  arg  >  0 

0O4B 

7E 

03 

jle 

dl4 

004  D 

8B 

7C  OA 

BOV 

dirLEN  »  then  use  it  as  counter 

0050 

dl4t 

0050 

8B 

OC 

BOV 

exrXl 

0052 

8B 

54  02 

BOV 

dx » Y 1 

0055 

8A 

44  08 

BOV 

air  COLOR 

0058 

33 

DF 

xor 

bx»b>: 

{duly  master  starts  =  O 

page 

» -  - 

-  top  of  vector  plotting  loop  - 

005  A 

dl5t 

005A 

E8 

0074  R 

C3l  1 

plotdot 

r plot  a  dot 

005D 

Bodify. 

.base 

label 

byte 

005  D 

41 

inc 

cx 

rldC/DEC  CX/DXt  adjust  long  axis  plr 

005  E 

81 

C3  1111 

3dd 

bx » 1 1 1 1 H 

!  rXdist  or  Ydist!  adjust  duty  master 

0062 

81 

FB  1111 

CBP 

bxfllllH 

{Ydist  or  Xdist!  check  cycle  position 

0066 

7E 

05 

Jle 

dl6 

{skip  if  short  axis  is  still  ok 

(Continued  on  next  page) 


76 
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Calling  the  Subroutine  from  BASIC 


0068 

81 

eb  ini 

sub 

b>: » 1 1 1 1 H 

JXdist  or  Ydistt  adjust  duty  master 

006C 

42 

inc 

dx 

.INC/DEC  DX/CXt  adjust  short  axis  ptr 

006D 

dl6t 

0O6B 

4F 

dec 

di 

*di  is  used  as  counter 

0O6E 

7D 

EA 

jse 

d  15 

» - 

»do  next  dot  if  not  finished 

0070 

5D 

POP 

bp 

*  always  restore 

0071 

CA 

0002 

ret 

2 

Jback  to  BASIC*  discard  1  srS  «EXIT« 

0074 

drauline  endp 

*this  routine 

plots  the 

pixel  at  column  CX  (0-31?  or  (0-639) 

» 

row  DX  (0-19?) 

> 

color  AL  (0-3)  or  (0-1) 

0074 

plotdot  proc 

near 

0074 

50 

push 

a>: 

0075 

57 

push 

di 

*BI0S  destroys  these  registers 

00  76 

B4 

0C 

mov 

ah*12 

»urite_dot  function 

0078 

CD 

10 

int 

10H 

*  video  I/O  call 

0O7A 

5F 

POP 

di 

007B 

58 

POP 

a>: 

007C 

C3 

ret 

007D 

plotdot  endp 

007D  csed  ends 


End  Listing  One 


Listing  Two 

'  TESTER. BAS  Dsn  Rollins  02/02/83 

'  this  cospiled  BASIC  program  tests  the  8088-code  DRAULINE  routine 

defint  a-z 
dim  vX(  5 ) 
screen  1 
io : 

input’routine  ( 1  or  2)'»r 
if  r=2  then  100 

20: 

input1’ color  (0-3*  -1  to  Quit  )*  *vX(  4  ) 
if  v%( 4 )  <  0  then  30 

input*  xl»yl*x2fy2*ivX(0)»vX(  1  )»v7.(  2  )»vX<3) 
vl(  5  )=0 

input" length  (null  =  full  line  )’’  * vZ( 5 ) 
call  drauline(  v£(  0 ) ) 

Soto  20 
30: 

screen  0»0*0»Q  twidth  80  lend 
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Listing  Two  (Listing  continued,  text  begins  on  page  72) 


'  LASER  BEAMS!  sample  use  of  the  length  parameter 
100 : 

els 

vZ(  0  )=159  tvZ( 1  )=(  199 )  ' XI »Y1  =  bottos  center  of  screen 

no: 

vZ(  2  )=int<  rnd*312  )  'X2  =  random  column 

vZ(3)=0  'Y2  =  top  of  screen 

vZ(4)=3  'color  =  uhite 

for  length=10  to  190  step  10 

5 )=lensth  'set  length 

call  drauline(vX(0))  'draw  Fartial  line 

next 

vZ(4)=0  'color  =  black,  to  erase 

for  lenSth=10  to  190  step  10 

v%<5)=iensth 
call  drawlinet  v7.(  0 ) ) 
next 


if  inKey$=""  then  110  else  30  'any  Key  to  exit 

End  Listing  Two 
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CP/M  EXCHANGE 


by  Robert  Blum 


Take  a  Look  in  the  Public  Domain. . . 

Public  domain  software  libraries 
continue  to  grow  and  the  number  of  com- 
puterists  involved  in  related  activities  is 
virtually  exploding.  The  two  predominate 
groups  responsible  for  cataloging  and  dis¬ 
tributing  public  domain  software  are  the 
CP/M  Users  Group  (CPMUG)  and  the 
Special  Interest  Group  for  Microcomput¬ 
ers  (SIG/M).  Collectively  they  offer  over 
140  volumes  (almost  23  Mbytes)  crammed 
full  of  programs.  Many  smaller  groups 
specializing  in  specific  programming  lan¬ 
guages  and  machines  exist.  Most  have 
program  libraries  and  are  responsible  for 
many  of  the  software  contributions  of 
the  larger  groups. 

CPMUG  (1651  Third  Avenue,  New 
York,  New  York  10028)  is  the  single  larg¬ 
est  distributor  of  CP/M  public  domain 
software,  with  85  volumes  in  their  library. 
No  matter  what  your  needs,  from  utilities 
to  BASIC  business  software,  it  can  be 
found  in  their  catalog.  At  a  nominal  cost 
of  S12  per  volume,  a  better  bargain  can’t 
be  found.  Unfortunately,  one  stumbling 
block  exists.  With  each  new  computer 
comes  a  new  disk  format  and  stocking  all 
of  them  is  beyond  the  resources  of  most 
groups.  In  response  to  this  need,  a  few 
commerical  concerns  are  now  offering 
copies  of  the  original  disks  in  many  of  the 
more  popular  disk  formats. 

What  is  desperately  needed  is  some 
universal  form  of  machine-readable  me¬ 
dia.  Since  none  are  currently  available, 
two  alternate  approaches  can  be  used. 
The  least  costly  is  “paperware.”  Even 
though  the  cost  is  low,  many  hours  will 
be  spent  keying  in  the  program  and  then 
finding  the  transcription  errors.  The  sec¬ 
ond  approach  requires  the  purchase  of  a 
modem.  With  a  300  baud  modem  you 
will  have  ready  access  to  a  number  of 
Remote  CP/M  (RCPM)  systems  across  the 
country.  Many  of  them  offer  complete 
libraries  of  public  domain  software  in 
addition  to  an  amazing  number  of  other 
useful  programs. 

One  often-overlooked  povnt  is  the 
educational  value  of  public  domain  soft¬ 
ware.  Many  fine  books  and  reference 
documents  are  available  to  provide  the 
prerequisite  training  on  the  computers 
instruction  set  and  the  CP/M  interface. 
But  none  can  rival  the  first-hand  experi¬ 
ence  of  stepping  through  a  working  pro¬ 
gram  with  a  debugger.  As  if  by  magic,  the 
mysteries  are  solved  as  you  watch  each 
instruction  execute. 


so 
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If  a  list  of  the  foremost  activists  in 
public  domain  software  were  made,  Ward 
Christensen  would  rank  in  the  top  ten. 
His  involvement  with  microcomputers 
began  with  their  inception.  As  librarian  of 
CPMUG,  he  exemplifies  dedication  to  the 
public  domain  scene.  To  ease  the  logjam 
of  phone  calls  to  his  RCPM  system  he  has 
added  a  second  phone  line  as  an  “admin¬ 
istrative”  and  general  CP/M  message  sys¬ 
tem  (messages  deal  with  bug  fixes,  review¬ 
ing  and  cataloging  of  CPMUG  disks,  etc.). 
Use  312-849-1132  (and  the  new  “M” 
command  and  “CPMUG”  password)  to 
download  the  current  CPMUG  catalog  of 
programs  (not  the  individual  files),  retrieve 
a  copy  of  the  user  group  contribution 
form,  send  in  a  contribution,  etc.  The 
original  CBBS  in  Chicago  is  at  312-545- 
8086,  which  supports  baud  rates  of  1 10- 
600.  Press  return  several  times  for  speed 
detect.  When  using  these  numbers,  be 
patient  —  they  get  a  lot  of  activity. 

Periodically,  I  will  be  reviewing 
programs  from  the  public  domain  that 
provide  topical  information.  For  the 
edification  of  those  who  are  interested,  I 
will  offer  complete  program  listings  along 
with  the  review  at  my  cost  of  printing 
and  shipping. 


...at  SD-44 

Displaying  the  diskette  directory  is 
probably  one  of  the  most-used  functions 
of  CP/M.  Unfortunately,  the  built-in 
command  DIR  produces  an  unsorted, 
single-column  display  which  is  hardly 
satisfactory  when  several  hundred  file 
names  are  to  be  scanned.  CPMUG  volume 
85  contains  SD-44,  which  I  believe  is  the 
latest  version  in  a  series  of  full-feathered 
directory  programs.  The  display  produced 
is  sorted,  and  three  columns  wide.  Each 
file’s  size  is  given  and  the  total  space  re¬ 
maining  on  the  diskette  is  calculated.  This 
may  sound  like  a  description  of  many 
others  but  SD-44  offers  a  number  of  other 
features.  The  eight  options  recognized  are: 

S  —  system  option:  includes  files  in  the 
output. 

F  —  file  option:  echoes  the  directory  out¬ 
put  to  a  disk  file  on  the  default  drive, 
named  “SD.DIR.”  If  SD.DIR  already 
exists,  then  the  directory  output  will 
be  appended  to  the  end  of  the  file. 
Otherwise,  SD.DIR  will  be  created  as 
a  new  file. 


U  —  user  option:  allows  the  specification 
of  the  user  number  for  the  directory 
in  the  form  “Un”  where  the  user 
number,  n,  must  be  greater  than  0 
and  no  larger  than  15.  This  option 
allows  no  spaces  between  “U”  and 
n,  and  cannot  be  used  on  pre-CP/M 
2.0  systems. 

A -all  users:  displays  directories  of  all 
user  areas  starting  at  the  user  area 
specified  in  the  U  option.  If  the  U 
option  is  omitted,  displays  start 
with  the  default  user  area  and 
continue  up  to  MAXUSR. 

R— reset  option:  provides  automatic  re¬ 
setting  of  the  disk  prior  to  perform¬ 
ing  directory  seach,  updating  the 
allocation  vector.  Same  as  doing  a 
Ctrl-C  when  changing  disks,  but 
handy  if  you  didn’t  (such  as  when 
running  a  SUBMIT  file).  The  RESFLG 
equate  will  force  the  R  option  un¬ 
conditionally  each  time  SD  is  run. 

N  —  no  page  option:  unconditionally  dis¬ 
ables  the  page  pause  option.  SD  will 
not  put  the  page-pause  prompt  into 
the  output  file. 

P  —  printer  option:  forces  all  console  out¬ 
put  to  be  echoed  to  the  CP/M  list 
device,  with  the  most  significant  bit 
set  to  0. 

D— all  disk  option:  allows  SD  to  search 
all  disk  drives  online  starting  with  the 
disk  drive  specified  or  implied  in  the 
command  line  filename. 

Outside  of  the  obvious  usefulness  of 
SD-44,  most  of  the  techniques  described 
in  my  series  on  BIOS  internals  can  be 
found  in  this  program.  If  you  want  a 
paperware  copy  of  SD-44  and  its  docu¬ 
mentation,  send  $5.00  to  the  address  at 
the  end  of  this  column. 


More  on  CP/M  Plus 

The  real  story  behind  CP/M  Plus’s 
features  unfolds  when  the  BDOS  func¬ 
tions  are  examined.  Rather  than  include 
all  the  BDOS  functions,  Table  I  (page  82) 
only  lists  the  additions  and  changes. 

Many  of  the  BDOS  functions  are 
now  MP/M  compatible.  This  fact  makes 
me  wonder  what  DR  has  in  mind  for  fu¬ 
ture  releases;  possibly  adding  concurrent 
operation  to  CP/M  or  providing  a  natural 
upgrade  path  to  MP/M.  Whatever  the 
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case,  to  make  full  use  of  all  the  new 
features  will  require  some  changes  to  the 
application  program.  Whether  CP/M  2.2 
programs  will  run  without  change  under 
CP/M  Plus  is  a  question  that  can  best  be 
answered  by  running  it.  Providing  trick 
code  has  been  kept  to  a  minimum,  the 
success  ratio  should  be  high. 

Next  month  I  will  continue  with 
memory  mapping  and  more  on  CP/M 
Plus’s  internals.  You  can  reach  me  directly 
if  you  want  to  order  paperware  for 
SD-44,  or  to  discuss  subjects  from  this 
column,  at:  Bob  Blum,  5536  Colbert 
Trail,  Norcross,  Georgia  30092;  (404) 
449-8948. 


Table  I. 

CP/M  Plus  BDOS  function  addition  and  changes. 


3  —  Auxiliary  Input:  same  as  CP/M 

2.2  reader  input. 

4  —  Auxiliary  Output:  same  as  CP/M 

2.2  punch  output. 

7  —  Auxiliary  Input  status:  new  func¬ 

tion  call  to  test  whether  data  is 
available  at  the  auxiliary  input 
device.  Under  CP./M  2.2  was 
Get  I/O  Byte. 

8  —  Auxiliary  Output  status:  new 

function  call  to  test  whether 
data  can  be  sent  to  the  auxiliary 
device.  Under  CP/M  2.2  was 
Set  I/O  Byte. 

38  —  Access  Drive:  MP/M  function  call, 

provided  for  compatibility  only. 

39  —  Free  Drive:  MP/M  function  call, 

provided  for  compatibility  only. 

41  —  Test  and  Write  Record:  MP/M 

function  call,  provided  for  com¬ 
patibility  only. 

42  —  Lock  Record:  MP/M  function 

call,  provided  for  compatibility 
only. 

43  —  Unlock  Record:  MP/M  function 

call,  provided  for  compatibility 
only. 

44  —  Set  Multi-Sector  Count:  allows 

from  1  to  128  128 -byte  sectors 
to  be  read  or  written  in  one 
operation.  MP/M  compatible. 

45  —  Set  BDOS  Error  Mode:  deter¬ 

mines  how  errors  are  handled. 
MP/M  compatible. 

46  —  Get  Disk  Free  Space:  determines 

how  many  free  128 -byte  sectors 
there  are  on  the  specified  drive. 
MP/M  compatible. 

47  —  Chain  to  Program:  allows  auto¬ 

matic  chaining  from  one  program 
to  another.  MP/M  compatible. 

48  -  Flush  Buffers:  forces  any  remain¬ 

ing  records  marked  for  writing 
to  be  written.  MP/M  compatible. 

49  —  .Get /Set  System  Control  Block: 

allows  the  system  control  block 
to  be  changed. 

50  —  Direct  BIOS  Calls:  allows  direct 

BIOS  calls  to  be  made  through 
BDOS  functions.  CP/M  Plus  no 
longer  supports  direct  BIOS  calls. 

59  —  Load  Overlay:  load  a  Resident 

System  Extension  (RSX)  or 
overlay  into  memory. 

60  —  Call  Resident  System  Extension: 

special  function  for  loading 
RSXs  only. 


98  —  Free  Blocks:  returns  to  free 

space  any  blocks  that  have  been 
allocated,  but  not  permanently 
recorded  on  disk. 

99  —  Truncate  File:  truncates  the 

specified  file  to  the  indicated 
random  record  number. 

100—  Set  Directory  Label:  creates  or 
updates  the  directory  label  which 
indicates  what  extended  direc¬ 
tory  options  are  active.  For 
example,  perform  access  date 
and  time  stamping.  MP/M  com¬ 
patible. 

101—  Return  Directory  Label  Data: 
returns  the  directory  label  data 
byte.  MP/M  compatible. 

102  —  Read  File  Date  Stamps  and  Pass¬ 
word  Mode:  returns  password 
and  time  stamp  mode  for  speci¬ 
fied  file.  MP/M  compatible. 

103—  Write  File  XFCB:  creates  or  up¬ 
dates  the  XFCB  for  a  specified 
file.  MP/M  compatible. 

104—  Set  Date  and  Time:  sets  the 
internal  date  and  time.  MP/M 
compatible. 

105  —  Get  Date  and  Time:  returns  the 

internal  date  and  time.  MP/M 
compatible. 

106  —  Set  Default  Password:  allows  set¬ 

ting  of  a  file  password  before  a 
file  is  accessed.  MP/M  compatible. 
107—  Return  Serial  Number:  returns 
the  6-byte  CP/M  Plus  serial 
number. 

108  —  Get/ Set  Program  Return  Code: 

allows  a  program  to  set  a  termi¬ 
nation  code  for  access  by  other 
programs  which  may  follow. 

109  —  Get/ Set  Console  Mode:  allows 

setting  of  control  parameters  for 
certain  BDOS  console  functions. 
110—  Get/ Set  Output  Delimiter:  allows 
the  string  delimiter  used  in  func¬ 
tion  9  to  be  set  to  another  value. 

111  —  Print  Block:  print  the  block  of 

data  pointed  to  by  a  CCB  on  the 
console. 

112  —List  Block:  print  the  block  of 

data  pointed  to  by  a  CCB  on  the 
system  list  device. 

152—  Parse  Filename:  parse  a  filename 
and  prepare  a  file  control  block 
for  use. 
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OF  INTEREST 


by  Michael  Wiesenberg 


Impressions  of  the 

West  Coast  Computer  Faire 

It  seems  de  rigueur  for  computer 
columnists  to  chronicle  their  impres 
sions  of  the  Computer  Faire,  so  here 
are  mine.  As  you  all  Know,  the  West 
Coast  Computer  Faire,  run  by  Jim 
Warren  (one  of  DDJ’s  first  editors), 
happens  each  spring  at  San  Francisco’s 
Civic  Auditorium  and  Brooks  Hall, 
with  symposia  and  workshops  at  the 
San  Franciscan  and  Holiday  Inn  hotels. 
Many  call  the  Faire  the  most  important 
microcomputer  conference  of  the  year. 

It  was  more  crowded  than  last 
year.  Also  more  hype.  The  most  im¬ 
pressive  display  was  that  of  Perfect 
Software,  obviously  designed  with  great 
thought  by  marketing  folks.  Some 
computer  businesses  are  just  beginning 
to  realize  that  good  products  don’t 
necessarily  sell  themselves;  they  have 
to  be  sold.  The  Perfect  folks  used  the 
principle  well,  as  they  lured  you  up  a 
carpeted  ramp  lit  on  either  side  by 
flashing  bulbs  synchronized  to  simulate 
a  lighted  path  travelling  into  the  dark¬ 
ened  interior  recesses  wherein  brilliant 
blue  laser  blasts  pierced  clouds  of 
smoke.  Displays  and  booths  everywhere 
else  in  the  Faire  were  out  in  the  open 
and  jammed  up  against  the  wares  of 
other  companies;  but  PS  had,  probably 
at  considerable  expense,  bought  a  large 
corner  nook  and  turned  it  into  a  mys¬ 
terious  subterranean  cave.  As  you 
stepped  off  the  ramp,  your  eyes 
slowly  adjusted  to  the  gloom  and  you 
found  yourself  on  a  railed  platform 
from  which  two  staircases  descended 
into  a  maze  of  monitors  on  pedestals, 
all  displaying  Perfect  Software  prod¬ 
ucts.  Giant  frameworks  of  steel  girders 
supported  laser-emitting  devices  that 
randomly  shot  blue  pencils  of  light 
above  the  heads  of  the  crowd,  creating 
moire  patterns  in  clouds  of  dry-ice 
steam.  A  disembodied,  amplified, 
sepulchral  voice,  describing  the  virtues 
of  various  Perfect  products,  floated 
through  and  around  the  din  of  the 
crowd. 

Elsewhere,  Texas  Instruments  put 
on  a  robot  show.  A  wheeled  contrap¬ 
tion  carrying  a  TI  99/4A  on  a  tray, 
having  a  TV  lens  for  a  face  and  a 
monitor  mirroring  all  it  saw  where  its 
mouth  belonged,  wandered  through 
the  crowd  near  the  TI  booth,  trading 
wisecracks  with  a  “real”  person  dressed 
up  as  Charlie  Chaplin  (and  symbolizing, 


perhaps,  the  dominance  of  the  TI  ma¬ 
chine  over  IBM?)  and  carrying  on 
apparently  intelligent  conversations 
with  bystanders.  I  am  familiar  enough 
with  robotics  to  know  that  this  “robot” 
must  have  been  controlled  at  a  distance 
by  human  beings.  I  looked  around  for, 
but  could  not  find,  some  seemingly 
innocent  person  perpetually  draining  a 
coffee  cup,  but  in  actuality  speaking 
into  a  microphone  concealed  therein. 

Both  software  and  hardware  were 
on  sale  for  greatly  reduced  prices.  If 
you  know  precisely  what  you’re  look¬ 
ing  for,  computer  fairs  probably  have 
the  best  bargains  anywhere.  But, 
caveat  emptor:  not  all  of  the  exhibitors 
will  be  back  next  year. 

The  machine  that  impressed  me 
the  most  was  the  Dynalogic  Hyperion, 
the  truly  portable,  beautifully  designed 
16 -bit  system  that  I  described  last 
month.  The  version  I  saw,  the  Hyperion 
Plus,  costs  close  to  $5000,  but  you  can 
get  one  without  quite  so  many  bells 
and  whistles  for  under  $3400. 

The  machine  that  may  well  start 
a  new  trend  in  quality  low-cost  com¬ 
puting  is  the  Humdinger.  This  tiny 
Z80  color  computer  with  CP/M  (de¬ 
scribed  in  detail  below)  costs  but  $129 
yet  offers  features  found  only  in  com¬ 
puters  costing  literally  thousands  more. 

Ah,  yes,  then  there’s  Lisa.  Wonder¬ 
ful  machine.  Maybe  the  best  user  inter¬ 
face  for  a  micro  commercially  available. 
The  mouse  is  easy  to  use,  moves  quick¬ 
ly  anywhere  on  the  screen,  and  instan¬ 
taneously  displays  information  any 
way  you  want  it,  without  having  to 
touch  the  keyboard.  But  $10,000?  If 
they  want  to  compete  in  the  same 
ballgame  with  the  PC,  Apple  will  have 
to  price  Lisa  in  the  same  ballpark. 

Through  all  the  chaos  glided  Jim 
Warren  on  roller  skates,  constantly  co¬ 
ordinating  his  show  through  a  walkie- 
talkie  that  rarely  left  his  lips. 

In  addition  to  manufacturers  with 
products  to  display,  acquisition  editors 
for  major  publishers  kept  an  eye  out 
for  potential  authors  of  promising  ma¬ 
terial,  and  software  makers  were  on 
the  lookout  for  new  programs.  If  you 
have  a  book  or  software  to  sell,  you’ll 
find  buyers  at  the  Faire. 

On  Sunday  at  5  p.m.,  the  sated 
crowds  were  quickly  hustled  out  into 
some  of  the  worst  rain  San  Francisco 
had  experienced  in  years. 

I  was  suffering  from  sensory  over¬ 


load,  but  glad  I  had  attended.  The 
same  thing  happens  when  I  spend 
more  than  a  few  hours  at  a  first-rate 
art  museum. 


Hard  PHD  or 
Toaster  for  Your  System 

The  Computer  Service  Company 

offers  16  Mb  Winchesters  for  most  sys¬ 
tems  for  $2595,  8  Mb  for  $2195,  and 
double  5  Mb  removable  subsystems  with 
two  free  cartridges  for  $2795.  These  are 
variously  called  PHD  8x8,  PHD  4x4, 
PHD  8  x  8KP  (for  KayPro,  for  example), 
PHD  8x8S  (S - 100),  all  of  which  are 
514-inch  drives,  and  Toaster  (two  3.9- 
inch  drives).  The  systems  include  drive, 
parallel  interface,  Z8 0  adapter  (or  adap¬ 
ters  for  virtually  any  other  computer), 
transportability  between  computers, 
power  supply,  diagnostics,  format, 
sector  sparing  program,  driver,  six- 
month  warranty,  and  (here’s  the  best 
part)  free  installation  by  The  Comput¬ 
er  Service  Company,  FOB  Mountain 
View,  California.  While  I’m  giving  them 
a  mention,  The  Computer  Service 
Company  also  rents  all  kinds  of  com¬ 
puter  equipment,  from  Osbornes  at  $5 
a  day,  dot  matrix  printers  at  $2.50, 
floppy  disk  drives  at  $2.50,  hard  disks 
at  $7.50,  to  monitors  at  $1.25  (add 
about  one-third  to  include  service), 
and  they  offer  phone  consultation  on 
all  forms  of  hardware  and  software 
maintenance  and  design  for  $35  per 
hour.  Reader  Service  No.  101. 


Graphics  Like  A  Word  Processor 

Graphics  Processing  System,  for 
48 K  Apple  II  Plus,  from  Stoneware, 
manipulates  and  edits  images  like  a 
word  processor.  It  will  also  mix  and 
change  colors  at  will,  edit  or  erase  a 
portion  of  a  picture  merely  by  defining 
its  boundaries,  zoom  or  reduce  any 
portion  of  a  picture  four  or  16  times 
(with  the  stored  image  having  a  greater 
resolution  than  that  on  screen,  repro¬ 
ducible  depending  on  the  capabilities 
of  the  printer  or  plotter),  rotate  images 
in  two  dimensions,  duplicate  images 
on  screen  and  to  and  from  disk,  change 
proportionality  of  portions  or  all  of 
images,  overlay  in  separate  colors,  and 
access  the  16K  RAM  card.  The  system 
is  compatible  with  graphics  tablets. 
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light  pens,  and  various  plotters  and 
graphics  printers.  SI 79.  Reader  Service 
No.  103. 


A  Good  Case 

Comp  Cases  by  the  Computer  Case 
Company  make  almost  any  small  sys¬ 
tem  portable,  inexpensively.  Literally  a 
custom  built  suitcase  that  exactly  fits 
your  IBM  PC,  Apple,  TRS-80,  etc., 
various  monitors,  printers,  and  other 
accessories,  the  Comp  Case  is  built 
from  mahogany  plywood,  has  padded 
handles,  brass  hardware,  key  locks, 
vinyl  cover,  triple-thick,  saddle-stitched 
vinyl  at  the  edges,  rubber  feet,  custom 
interior  foam  padding,  nylon  velcro 
straps,  and  interlocking  top  and  base. 
Once  your  system  is  in  a  Comp  Case, 
you  need  never  remove  it,  so  you  can 
leave  cabling  in  place  and  easily  set  up 
the  system.  Comp  Cases  vary  in  price 
from  less  than  $100  for  many  peripheral 
or  accessory  cases,  to  $109  fora  hous¬ 
ing  for  Apple  11  with  one  drive,  to 
$129  for  Apple  II  with  two  drives  and 
a  monitor  or  TRS-80  Model  III,  to 
$139  for  Apple  III  with  drives  and 
printer.  Reader  Service  No.  105. 


A  Real  Humdinger 

The  Humdinger  from  Venture  Mi¬ 
cro  is  a  Z80  color  computer  with  a 
“real”  keyboard,  4K  RAM,  8K  BASIC 
in  ROM,  eight-color  video,  four-voice 
sound  generator,  free  game  cartridge, 
RF  modulator,  and  parallel,  serial,  cas¬ 
sette,  cartridge,  joystick,  expansion, 
and  EPROM  interfaces,  for  $129.  You 
can  add  16K  RAM  for  $39.95,64K  for 
$99,  voice  synthesizer  for  $69.95,  disk 
controller  for  $75,  S’A-ineh  drive  for 
$210,  CP/M  for  $79,  word  processor 
for  $45,  Pascal  for  $59,  an  8088  for 
$119  (you’ll  also  need  the  8088  BASIC 
ROM  for  $124.95),  and  an  8087  for 
$299,  travel  case,  graphics  table,  80-by- 
24  video,  user-defined  graphics,  real 
time  clock  calendar,  editor/assembler, 
various  game  cartridges  and  cassettes, 
extended  BASIC,  COBOL,  Forth,  C, 
Logo,  and  Pilot.  Ten  new  cartridge 
and  cassette  programs  per  month  are 
planned.  Reader  Service  No.  107. 


Dot  Matrix  Printer 
with  Daisy  Wheel  Quality 

The  Santee  S700  Printer  from 
Western  Technology  offers  letter  qual¬ 
ity  by  printing  each  line  four  times 
with  minute  advances  between  passes. 


at  a  throughput  of  32  to  58  cps.  Since 
it  prints  960  dots  per  inch,  you’ll  need 
a  magnifying  glass  to  distinguish  this 
mode  from  a  daisy  wheel  output.  A 
correspondence  mode  makes  two  passes 
at  each  line,  with  quality  better  than 
that  of  the  best  dot  matrix  printers,  at 
a  throughput  of  65  to  195  cps.  And 
the  draft  quality  mode  is  as  good  as 
the  best  dot  matrix  printers.  Up  to  12 
fonts,  ranging  in  size  from  7  to  12 
points,  can  be  intermingled  simultane¬ 
ously,  with  no  pause  in  printing.  For¬ 
matting  commands,  inserted  in  the 
text,  are  performed  by  the  printer, 
rather  than  the  computer,  with  total 
user  control  over  margins,  spacing,  tab 
settings,  justification  (incremental  and 
proportional),  centering,  boldface,  un¬ 
derlining,  and  graphics.  This  remarkable 
printer  costs  under  $4000.  Spellbinder, 
the  CP/M  word  processing  software 
from  Lexisoft,  has  a  special  version 
configured  for  the  Santee.  Reader  Ser¬ 
vice  No.  111. 


Two  APLs 

VIZ::APL  from  EASI  APL  Sys¬ 
tems  is  virtual -memory  APL  for  Z80 
microcomputers,  and  some  16-bit 
microcomputers  with  a  Z80  board. 
This  full  implementation  of  APL  has 
an  overlaid  interpreter  and  virtual 
work  area  limited  only  by  disk  space, 
runs  under  CP/M,  interfaces  with 
high -resolution  graphics,  uses  double¬ 
precision,  floating-point  arithmetic, 
and  has  dynamic  symbol  table  alloca¬ 
tion.  I  saw  the  language  demonstrated 


The  EUY-3T  thermal  printer  from 
Panasonic  is  about  the  size  of  a  good 
5 -cent  cigar  (“What  this  country  needs 
is  a  good  .  .  .”  inexpensive  printer), 
4.69  by  1.79  by  2.64  inches.  With  dot- 
addressable  graphics,  40  characters  per 


on  an  Osborne  I  at  the  West  Coast 
Computer  Faire,  and  was  impressed 
with  its  fast,  direct-mode  vector  calcu¬ 
lations  and  transformations.  No  price 
on  this  one,  but  use  the  Bingo  Card 
for  more  information.  Reader  Service 
No.  115. 

APL. 68000  by  the  Computer 
Company  is  a  full  APL  that  runs  under 
CP/M-68K,  UNIX,  and  VersaDOS  on 
the  Sage  Models  2  and  4,  Forward 
Technology’s  Gateway  Work  Station 
microcomputers,  the  Pixel  100AP,  the 
Corvus  Concept,  and  “soon”  on  all 
68000-based  micros.  Reader  Service 
No.  117. 


1/4 

The  Forth-79  Version  2  compiler 
from  MicroMotion  for  most  Z80  CP/Ms 
1.4  and  2.whatever,  including  Apple, 
comes  with  screen  editor,  macroassem¬ 
bler,  string  processing,  three-bit  arith¬ 
metic,  floating  point,  200  pages  of 
tutorial  and  reference  documentation, 
and  hi-res  for  Apple  and  North  Star, 
and  costs  from  $99.95  (doesn’t  any¬ 
thing  ever  sell  for  an  even  $100?)  to 
$139.95.  Reader  Service  No.  119. 


Wooden  Clay  ? 

Perhaps  one  of  the  better  pieces 
of  inexpensive  software  for  the  IBM 
PC  seen  at  the  West  Coast  Computer 
Faire  was  Cosmic  Night  ware  from 
Wood  &  Clay  Hi-Tech  Gameware. 
“Earth  explodes,”  they  say  (I  saw  it 


line,  battery  power,  bi-directional 
printing  at  1.2  lines  per  second,  and  a 
weight  of  14  ounces,  the  printer  will 
cost  under  $100  in  OEM  quantities. 
Reader  Service  No.  109. 


Hot  Little  Printer 
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happen  —  wonderful  graphics),  “and 
you’re  the  only  one  left!  All  the  phan¬ 
toms  of  the  universe  are  released,  and 
you  have  to  fight  enemies  so  real  you 
won’t  believe  it’s  a  dream.”  The  disk 
costs  $32.50.  If  you  want  real  arcade 
action  on  your  PC,  you’ll  want  to  or¬ 
der  joystick  controllers  at  $29.95  each 
from  W&C.  Other  games  available 
include  Falklands  Fury,  with  “all  the 
action  of  real  life  warfare”  (whoopee!, 
what  fun!)  and  Jungle  Madness,  in 
which  you  “play  Tarzan,  swing  from 
vines,  and  fight  off  savage  pygmies,” 
also  $32.50  each.  (California,  add  6.5% 
sales  tax.)  Reader  Service  No.  121. 


The  Sorcerer  Lives! 

I  often  think  my  computer  system 
is  unusual  and  incompatible  with  any¬ 
one  else’s.  When  I  say  I  have  a  Sorcerer, 
most  people  say,  “A  what?”  So  I’m 
always  pleased  to  find  someone  trying 
to  keep  this  wonderful  Z80  machine 
alive.  In  this  case,  it’s  ISIS  (the  Inter¬ 
national  Sorcerer  Information  Service), 
a  “not-for-profit”  monthly  newsletter 
to  give  Sorcerer  owners  a  means  of  ex¬ 
changing  information.  Membership  is 
$15  in  Canadian  funds  in  Canada,  and 


US  dollars  elsewhere.  Contact  ISIS,  c/o 
Maurice  Dow,  84  Camberley  Cres., 
Brampton,  Ontario,  Canada  L6V  3L4; 
or  use  the  reader  service  card.  Reader 
Service  No.  123. 


Clock  Your  Apple 

dat.a.clock,  for  Apple  II,  II  Plus, 
and  lie,  from  P  &  B  Research  Consul¬ 
tants  keeps  time  in  date,  month,  and 
year,  with  a  two-  to  three-year  battery, 
has  an  externally  accessible  EPROM, 
and  costs  $55  in  kit,  or  $85  assembled 
(plus  $2  p&h).  Reader  Service  No.  113. 


Commodore  Camaraderie 

A  VIC-20  users  group  is  being 
formed  by  the  New  York  Amateur 
Computer  Club.  Although  the  UG  will 
meet  in  New  York  City,  NYACC  is 
soliciting  members  throughout  the 
country  to  join  “on  a  correspondence 
basis.”  Both  types  of  VIC-20  users  are 
sought,  computer  novices  and  the 
knowledgeable  who  bought  the  ma¬ 
chine  “just  for  the  fun  of  it.  What  we 
would  like  to  do  is  put  these  two  types 
together  and  get  some  synergism 
going.”  If  enough  interest  is  generated, 
NYACC  will  plan  to  expand  to  other 
Commodore  machines,  like  the  64  and 
the  Pet.  Reader  Service  No.  125. 


Make  a  Beeline  for  the  C  Line 

The  C  Line,  a  free  public  access 
electronic  bulletin  board  for  users  of 
UNIX  and  C,  has  close  to  two  mega¬ 
bytes  of  public  domain  C  software  just 
itching  to  be  downloaded  onto  the 
computers  of  those  with  any  standard 
terminal  or  computer  with  modem 
who  dial  (201)  625-1797,  8  pm  to  9  am 
weekdays  (Eastern  time)  and  24  hours 
weekends.  The  C  Line,  say  sponsors  In- 


foPro  Systems,  publishers  of  UNIQUE, 
the  UNIX  industry  newsletter,  and 
Perchwell  Corporation,  a  management 
research/consulting  firm  specializing  in 
UNIX,  “expects  to  receive  several  car¬ 
riage  returns  initially”  (ah,  anthropo¬ 
morphisms  abound!),  “and  will  auto¬ 
matically  adjust  itself  to  the  transmis¬ 
sion  speed  being  used,  from  110  to  710 
baud.”  Reader  Service  No.  129. 


Confer  Intelligently 

The  National  Conference  on  Arti¬ 
ficial  Intelligence,  sponsored  by  the 
American  Association  for  Artificial 
Intelligence,  takes  place  August  22  to 
26,  1983,  at  the  Washington  (D.C.) 
Hilton  Hotel.  Reader  Service  No.  131. 


Keeping  TABs 

TAB  Books’  Spring/ Summer  cata¬ 
log,  with  65  new  books  and  over  600 
titles,  includes  these  about  computers: 

Graphics  Programs  for  the  IBM  PC 
(256  pages,  $12.95  paper,  $18.95  hard¬ 
cover),  33  Games  of  Skill  and  Chance 
for  the  IBM  PC  (256/$  14.95/S21 .95), 


and,  possibly  a  good  one  for  would-be 
hardware  tech  writers , Beginner’s  Guide 
to  Reading  Schematics  (140/S8.95/ 
$13.95),  all  by  Robert  Traister. 

100  Ready-to-Run  Programs  and  Sub¬ 
routines  for  the  IBM  PC,  by  Jeff  Bretz 
and  John  Craig  (320/$  15 .95/S22 .95 ). 
Programming  Your  Atari  Computer, 
by  Mark  Thompson  (280/510.95/ 
$16.95). 

Advanced  Programming  Techniques 
for  Your  Atari,  including  Graphics  and 
Voice  Programs,  by  Linda  Schreiber 
(224/5 13. 95/$  19. 95). 

25  Graphics  Programs  in  Microsoft 
BASIC,  by  Timothy  O’Malley  (160/ 
$10.95/517.95). 

101  Projects  for  the  Z-80,  by  Frank 
Tedeschi  and  Robert  Colon  (368/ 
$16.95/523.95). 

Troubleshooting  and  Repairing  Person¬ 
al  Computers,  by  Art  Margolis  (320/ 
$13.95/519.95). 

Microcomputer-Controlled  Toys  and 
Games  and  How  They  Work,  by  Van 
Waterford  (240/59.95/517.95). 
Experiments  in  Four  Dimensions,  by 
David  Heiserman  (288/512.95/52 1.95). 


Learning  Simulation  Techniques  on  a 
Microcomputer  Playing  Blackjack  and 
Other  Monte  Carlo  Games,  by  Pat 
Macaluso  (154/510. 95/516. 95). 

Basic  BASIC -English  Dictionary  for 
the  Apple,  PET,  and  TRS-80,  by  Larry 
Noonan  (154/517.95,  hard  cover  only). 

The  Sinclair  ZX81,  by  Randle  Hurley 
(182/516.95,  hard  cover  only). 

Electronic  Components  Handbook  for 
Circuit  Designers,  by  R.H.  Warring, 
(336/513.95/521.95). 

Reader  Service  No.  127. 
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(Continued  from  page  10.) 

our  CP/M  2  system  had.  So  it  was  a  disap¬ 
pointment  to  find  that  an  assembly  that 
ran  in  25  seconds  under  CP/M  2  consumed 
23  seconds  under  CP/M  3.  A  ten  percent 
improvement  didn’t  seem  like  much  of  a 
return  on  our  investment  in  RAM  cards. 
We  set  out  to  find  out  what  the  CP/M  3 
BDOS  was  doing  with  all  those  buffers. 

Inter-Bank  Peeping 

We  wrote  an  experimental  tool  called 
SHOWBCB.  It  finds  and  dumps  the  two 
chains  of  the  BCBs  to  the  console.  This 
is  not  easy,  because  the  Disk  Parameter 
Header,  the  chain  anchors,  and  all  the 
BCBs  are  in  bank  zero,  while  the  program 
runs  in  bank  one.  It  is  made  possible  by 
the  XMOVE  and  MOVE  BIOS  functions. 
MOVE  is  normally  an  intra-bank  block 
copy  function.  If  XMOVE  is  called  first 
to  inform  MOVE  of  the  source  and  target 
bank  numbers,  the  next  call  on  MOVE 
will  transfer  data  from  a  source  address  in 
one  bank  to  a  target  address  in  another. 
With  them,  our  program  could  get  copies 
of  the  control  blocks  into  bank  one  so  it 
could  display  them. 

One  problem  slowed  us  down  for  a 
few  hours.  The  program  was  written  to 
play  by  the  rules  of  CP/M  3,  making  its 
BIOS  calls  by  way  of  BDOS  function  50. 
It  turns  out,  however,  that  the  BDOS  uses 
MOVE  (and  XMOVE?)  in  the  course  of 
executing  function  50.  So  by  the  time 
we  reached  the  BIOS  for  the  MOVE  func¬ 
tion,  the  BDOS  had  already  been  there 
and  thus  had  used  up  the  parameters  we 
had  given  to  XMOVE.  What  we  meant  for 
an  inter-bank  move  was  thus  magically 
transformed  into  an  intra-bank  move.  We 
reverted  to  calling  MOVE  and  XMOVE 
directly.  This  is  possible  provided  that 
the  BIOS  routines  and  the  calling  pro¬ 
gram’s  stack  are  all  in  non-banked 
storage. 

The  Directory  BCB  Chain 

Examine  Figure  1  (page  91).  It  shows 
the  BCB  chain  immediately  after  a  cold 
start.  The  only  disk  I/O  that  has  been 
done  to  this  point  is  the  load  ofCCP.COM 
and  its  load  of  SHOWBCB.COM.  The 
lengthy  display  of  the  data  BCBs  has  been 
trimmed  to  save  space. 

The  first  byte  of  a  BCB  is  the  number 
of  the  drive  for  which  it  holds  a  sector, 
and  FFh  indicates  an  unused  buffer.  Only 
one  BCB  is  active  in  each  chain.  In  the 
directory  chain  you  can  see  that  four 
BCBs  have  been  used,  but  three  of  them 
have  since  been  discarded.  Old  BCBs  for 
track  2  sectors  1,  2,  and  4  can  be  seen. 
Presumably  sector  3  was  read  as  well,  but 
its  BCB  doesn’t  show. 


Track  2  sector  4  was  read  again,  and 
its  BCB  is  still  active.  This  BCB  probably 
represents  the  I/O  done  to  open  SHOW¬ 
BCB. COM.  Thanks  to  its  directory  hash¬ 
ing  table,  the  BDOS  didn’t  have  to  scan 
the  directory  for  SHOWBCB;  it  was  able 
to  read  the  one  sector  that  contained  its 
entry.  However,  it  did  have  to  read  that 
sector  because  the  residual  BCB  for  the 
same  sector  had  been  discarded. 

This  seems  reasonable  on  reflection. 
It’s  only  by  reading  a  directory  sector  and 
testing  its  contents  against  the  hash  table 
that  the  BDOS  can  detect  a  change  of 
disks.  If  it  didn’t  make  that  test,  it  would 
be  as  liable  to  trash  a  directory  as  MSDOS 
is.  Extra  directory  I/O  is  a  reasonable 
price  to  pay  to  avoid  that  danger  to  data 
integrity,  so  the  fact  that  the  BDOS  seems 
to  toss  away  its  active  directory  BCBs 
shouldn’t  disturb  us  too  much. 

The  Data  BCB  Chain 

Now  look  at  the  chain  of  data  BCBs. 
Two  have  been  used,  but  only  one  remains 
active.  The  discarded  one  probably  repre¬ 
sents  the  last  sector  of  CCP.COM;  track  4 
sector  6  is  about  the  right  location  for  it 
on  this  disk.  Of  course,  CCP.COM  occupies 
3.5  one-kilobyte  sectors.  Why  does  only 
one  BCB  appear?  Probably  because  the 
BIOS’s  cold-start  code  uses  a  multi-record 
read  to  load  the  file.  When  the  BDOS 
knows  it  will  be  transferring  eight  or 
more  128-byte  units  from  adjacent  disk 
locations  to  adjacent  storage  locations,  it 
probably  skips  allocating  a  deblocking 
buffer  and  reads  the  sector  directly  into 
storage.  The  last  sector  of  the  file  is  not 
all  used,  so  a  BCB  was  allocated  to  hold  it 
while  the  last  few  records  were  pulled  out 
of  it.  The  one  active  BCB  probably  repre¬ 
sents  the  only  sector  of  SHOWBCB.COM. 

Examine  the  addresses  in  the  “bcb” 
and  “link”  columns;  you  can  see  how  the 
BDOS’s  LRU  algorithm  works.  BEC3  is 
the  last  BCB  assembled  in  the  BIOS. 
When  the  system  is  loaded,  it  is  at  the  end 
of  the  chain.  Whenever  the  BDOS  needs  a 
BCB,  it  removes  the  last  one  from  the  end 
of  the  chain  and  inserts  it  at  the  head  of 
the  chain.  In  Figure  1 ,  you  can  see  that 
the  BCB  at  BEC3  was  moved  from  tail  to 
head,  and  the  same  was  done  to  the  BCB 
that  originally  preceded  it,  BEB4.  The 
original  chain  head,  BAA9,  has  aged  two 
positions.  We  can  tell  how  many  BCBs 
the  BDOS  has  used  by  counting  the  BCBs 
that  precede  BAA9.  This  remains  true 
only  for  71  uses,  when  the  chain  wraps. 

BCB  Use  for  Input 

Our  next  experiment  was  to  run  an 
assembly  that  did  input  but  no  output 
(“rmac  showbcb  $lbrzszpz”).  The  assem¬ 
bler  had  to  read  a  total  of  29  sectors:  ten 
sectors  of  SHOWBCB.ASM  (twice  each), 


and  nine  sectors  in  three  library  files. 
Figure  2  (page  91)  shows  the  data  BCBs 
afterward.  The  only  one  still  active,  BE4B, 
represents  the  load  of  SHOWBCB.COM. 
The  two  oldest,  BEB4  and  BEC3,  are  left 
over  from  Figure  1 .  The  six  in  between 
are  the  total  result  of  loading  RMAC, 
reading  the  source  file  twice,  and  reading 
three  libraries.  The  BCB  at  BE  A5  probably 
represents  the  last  sector  of  RMAC  (it, 
like  CCP.COM  earlier,  would  have  been 
loaded  with  a  multi-record  read).  That 
leaves  five  BCBs  to  account  for  all  29 
sectors  of  data. 

Two  things  stand  out  in  Figure  2. 
First,  the  BDOS  does  not  use  a  new  BCB 
for  every  new  sector  of  data  it  reads.  If  it 
did,  Figure  2  would  be  24  BCBs  longer 
than  it  is.  Perhaps  the  BDOS  assigns  only 
one  BCB  to  each  open  file  (three  libraries 
plus  the  source  file  twice  equals  five). 
Perhaps  it  reuses  a  BCB  whenever  its  cur¬ 
rent  sector  is  completely  used  up  and  the 
next  sector  is  for  the  next  adjacent  record 
of  the  file.  The  second  scheme  would  pro¬ 
duce  the  same  numbers  in  this  case  of 
all-sequential  I/O,  but  would  allow  for 
the  accumulation  of  more  BCBs  to  a 
direct -access  file. 

Either  way,  the  result  is  that  for  se¬ 
quential  input,  the  BDOS  effectively 
assigns  a  single  BCB  to  each  open  file. 
Sequential  data  does  not  accumulate  in 
the  BCB  chain.  When  a  file  is  used  twice 
in  succession  (as  is  the  source  file  in  an 
assembly),  it  will  be  read  twice  from  disk. 
The  only  effect  of  the  BCB  chain  is  to 
eliminate  the  second  read  of  the  last 
sector.  Now  we  can  see  why  an  assembly 
runs  at  essentially  the  same  speed  in  CP/M 
3  and  CP/M  2. 

The  second  thing  that  stands  out  in 
Figure  2  is  that  what  little  data  was  accu¬ 
mulated  has  since  been  discarded.  The 
data  residual  from  RMAC’s  execution  was 
tossed  out  sometime  between  the  end  of 
RMAC  and  the  start  of  SHOWBCB.  The 
culprit  had  to  be  the  CCP  —  it  was  the 
only  program  to  run  in  that  interval.  We 
ran  CCP.COM  under  SID  to  see  what  it 
would  do. 

What  it  did  was  issue  BDOS  request 
98,  Free  Blocks.  This  BDOS  function  is 
supposed  to  release  any  disk  blocks  that 
were  allocated  to  files  that  were  never 
closed.  It  recovers  disk  space  that  might 
otherwise  remain  inaccessible  until  the 
disk  was  logged  in  again  (possibly  a  long 
time  in  CP/M  3,  since  disks  are  only  logged 
in  when  control-C  is  pressed).  Exactly 
that  problem  occurs  under  MSDOS  when 
the  IBM  Pascal  compiler  aborts,  but  under 
MSDOS  you  have  to  run  CHKDSK  to  re¬ 
cover  the  space. 

BDOS  function  98  has  a  laudable 
goal,  but  it  seems  to  have  an  unfortunate 
side  effect.  It  not  only  cleans  up  the  allo¬ 
cation  vector,  it  also  puts  FFh  into  every 
active  BCB  !  We  proved  that  by  killing  the 
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call  on  function  98  in  CCP.COM  (it’s  at 
location  458h)  and  re-running  the  experi¬ 
ments.  With  the  modified  CCP,  the  BCB 
chain  after  the  assembly  had  eight  active 
entries  instead  of  eight  dead  ones  and 
one  live.  However,  this  had  little  effect 
on  performance,  since  the  active  entries 


represented  only  the  last  sectors  of  their 
respective  files. 

BCB  Use  for  Output 

We  checked  BCB  use  following  an 
assembly  that  produced  PRN,  REL,  and 
SYM  files.  We  expected  to  see  BCBs  for 


at  least  the  last  sector  of  each  output  file. 
We  did  not.  We  don’t  know  what  space 
the  BDOS  is  using  to  block  the  physical 
sectors  of  output  files,  but  it  isn’t  space 
taken  from  the  BCB  chain. 

To  make  sure  that  we  weren’t  seeing 
the  result  of  some  clever  use  of  multi¬ 
record  writes  in  RMAC,  we  ran  a  test  using 
the  Magic  Wand  PRINT  program  with 
disk  output.  This  program  has  abysmal 
disk  I/O  logic;  it  alternates  reading  and 
writing  of  128 -byte  units.  Under  CP/M  2, 
with  a  BIOS  that  had  only  a  single  sector 
buffer,  PRINT  caused  a  seek,  read,  seek, 
read,  write  sequence  for  every  128  bytes 
of  throughput.  Under  our  2.2  BIOS  with 
separate  read  and  write  sector  buffers, 
it  ran  better.  In  fact,  it  ran  better  than 
under  CP/M  3,  where  PRINT  takes  about 
10%  longer  than  under  our  improved  2.2 
BIOS !  And  its  output  didn’t  leave  any 
evidence  in  the  BCB  chain. 

Here  again,  it  seems  that  the  CP/M  3 
BDOS  is  throwing  away  an  opportunity 
to  speed  up  processing.  All  output  goes 
straight  to  disk;  if  it  then  becomes  input, 
it  has  to  be  read  back  again.  The  file  that 
one  program  writes,  another  program  is 
going  to  read.  The  editor’s  output  is  input 
to  RMAC;  RMAC’s  REL  file  is  input  to 
LINK;  and  its  PRN  file  is  input  to  TYPE 
or  PIP.  It’s  all  very  well  to  speed  up  direct 
access,  but  we  should  keep  in  mind  that 
(1)  the  majority  of  CP/M  commands  read 
files  sequentially,  and  (2)  commands  are 
used  in  sequence,  with  the  output  of  one 
feeding  the  input  of  the  next.  That  situa¬ 
tion  is  exactly  right  for  the  LRU  algorithm, 
but  the  BDOS  isn’t  capitalizing  on  it. 

Well,  almost  exactly  right.  If  the 
BDOS  buffered  all  the  sectors  it  read,  and 
also  buffered  all  the  sectors  it  wrote, 
some  problems  would  arise.  If  an  output 
file  was  larger  than  the  total  buffer  pool, 
its  last  few  sectors  would  displace  its  first 
few.  The  next  command’s  input  of  the 
first  few  sectors  of  the  file  would  kick 
out  the  next  few,  and  so  on.  A  ripple 
would  run  down  the  BCB  chain,  causing 
each  saved  sector  to  be  discarded  just  a 
few  sectors  before  it  was  needed  as  input. 

But  the  BDOS  does  not  buffer  all  the 
sectors  it  reads.  If  it  kept  the  present 
logic  for  sequential  reading  but  buffered 
all  output  sectors,  then  the  ripple  would 
never  develop.  One  BCB  would  be  used  to 
read  the  leading  sectors  that  had  been  dis¬ 
placed  by  later  output.  Eventually  the 
input  requests  would  work  around  to  the 
sectors  that  had  not  been  displaced.  From 
there  to  the  end  of  the  file,  the  second 
command  would  operate  at  RAM  speeds. 

Summary 

A  sophisticated  algorithm  for  sector 
buffering  under  CP/M  would  make  special 
provision  for  COM  files,  encouraging  the 
retention  of  commands  in  storage.  It 
would  probably  use  separate  chains  of 
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BCBs  for  input  and  output,  with  some 
kind  of  heuristic  to  shuffle  buffers  from 
one  chain  to  the  other  on  the  fly.  In  fact, 
CP/M  3  has  enough  resources  to  make  it 
quite  interesting  as  a  case  study  in  perfor¬ 
mance  optimization.  It  could  be  the  grist 
for  a  Ph.D.  thesis  in  Comp.  Sci.,  in  fact. 

But  the  existing  algorithm  is  not 
sophisticated  and,  while  it  may  be  effec¬ 
tive  for  direct  access,  it  is  definitely  not 
optimal  for  the  kind  of  sequential  access 
that  is  the  bread  and  butter  of  any  CP/M 
system.  Until  it  is  improved  (CP/M  3.2?), 
we  recommend  that  you  not  spend  a  lot 
of  money  on  RAM  cards  when  moving  to 
CP/M  Plus.  One  48Kb  system  bank  should 
provide  as  many  sector  buffers  as  the 
BDOS  can  use  effectively. 


•»J 


Dr.  Dobb’s  Journal,  Number  80,  June  1983 


Dr.  Dobb’s  Journal 


RED's  most  important  new  feature 
is  a  set  of  buffer  routines  which 
remove  all  restrictions  on  the  size 
of  files  which  may  be  edited.  The 
differences  between  RED  and  ED2 
are  all  under  the  covers .  .  . 


Dr.  Dobb  s  Journal 

For  Users  of  Small  Computer  Systems 


July  1983  Volume  8,  Issue  7 


Publisher  -  Clifford  West 
Editor  -  Reynold  Wiggins 
Managing  Editor  -  Craig  LaGrow 
Contributing  Editors  - 

Robert  Blum,  Dave  Caulkins, 

Dave  Cortesi,  Ray  Duncan, 

Michael  Wiesenberg 
Marketing  Director  -  Beatrice  Blatteis 
Advertising  Director  -  Carl  Landau 
Advertising  Sales  -  Doug  Millison 
Circulation  Manager  —  Gloria  Romanoff 
Circulation  Assistants  - 

Terri  Marty,  Linda  Marohn 
Production  Manager  -  Barbara  Ruzgerian 
Production  Assistants  - 

Alice  Hinton,  Ann  West 
Marianne  Tryens 
Typesetter  -  Paula  Fairchild 


Copyright  ©  1983  by  People’s  Computer 
Company  unless  otherwise  noted  on  specific 
articles.  All  rights  reserved. 

Subscription  Rates:  $2  5  per  year  within  the 
United  States;  $44  for  first  class  to  Canada 
and  Mexico;  $62  for  airmail  to  other  coun¬ 
tries.  Payment  must  be  in  U.S.  Dollars, 
drawn  on  a  U.S.  Bank. 

Writer’s  Guidelines:  All  items  should  be 
typed,  double-spaced  on  white  paper.  List¬ 
ings  should  be  produced  by  the  computer, 
using  a  fresh,  dark  ribbon  on  continuous 
white  paper.  Please  avoid  printing  on  perfo¬ 
rations.  Payment  is  in  contributor’s  copies. 
Requests  to  review  galleys  must  accompany 
the  manuscript  when  it  is  first  submitted. 
Authors  may  receive  a  copy  of  the  complete 
writer’s  guidelines  by  sending  a  self- 
addressed,  stamped  envelope. 

Donating  Subscribers  Contributing  Sub¬ 
scriber:  $  50/year  ($25  tax  deductible).  Re¬ 
taining  Subscriber:  $75/year  ($50  tax  de¬ 
ductible).  Sustaining  Subscriber:  $  100/year 
($75  tax  deductible).  Lifetime  Subscriber: 
$1000  ($800  tax  deductible).  Corporate 
Subscriber:  $S00/year  ($400  tax  deductible, 
receives  five  one -year  subscriptions). 

Contributing  Subscribers:  DeWitt  S.  Brown, 
Burks  A.  Smith,  Robert  M.  Connors,  Robert 
C.  Luckey,  Transdata  Corporation,  Mark 
Ketter,  John  W.  Campbell,  Friden  Mailing 
Equipment,  Frank  Lawyer,  Rodney  Black, 
Thomas  Davis,  Jan  Steinman,  G.  Hunter, 
Ronald  E.  Johnson,  Kenneth  Drexler, 
Real  Paquin,  Ed  Malin,  John  Saylor,  Jr., 
Ted  A.  Reuss  III,  Infoworld,  Stan  Veit, 
Western  Material  Control,  S.P.  Kennedy, 
Ed  Moran,  W.D.  Rausch,  John  and  Janith 
Hatch.  Lifetime  Subsriber:  Michael  S.  Zick. 

Foreign  Distributors  UK  &  Europe: 
Homecomputer  Vertriebs  HMBH  282,  ITu- 
gelstr.  47,  4000  Dusseldorf  1,  West  Germany; 
La  Nacelle  Bookstore,  Procedure  D’Abonne- 
ment  1-74,  2,  Rue  Campagne  —  Premiere, 
F-75014  Paris,  France;  Computercollectief, 
Amstel  312A,  1017  AP  Amsterdam,  Nether¬ 
lands.  Asia  &  Australia:  ASCII  Publishing, 
Inc.,  4F  Segawa  Bldg.  5-2-2,  Jingumae, 
Shibuya-Ku,  Tokyo  ISO,  Japan ;  Computer 
Services,  P.O.  Box  13,  Clayfield  QLD  4011, 
Australia;  Computer  Store,  P.O.  Box  31-261, 
22B  Milford  Rd.,  Milford,  Auckland  9,  New 
Zealand.  ( Write  for  Canadian  distributors) 


CONTENTS 


ARTICLES - 

12  Augusta,  Part  IV  —  The  Augusta  Compiler  (continued) 

by  Edward  Mitchell 

Concluding  the  four-part  series  on  his  tiny  language,  author  Mitchell  describes  the 
internal  operation  of  the  Augusta  compiler.  Included  are  details  of  the  lexical 
analyzer,  the  symbol  table,  code  generation,  and  backpatching  techniques,  as  well 
as  some  personal  comments  on  Ada,  Microsoft  BASIC,  and  overall  development 
of  the  compiler. 

34  RED  —  A  Better  Screen  Editor,  Part  I 

by  Edward  K.  Ream 

In  our  January  1982  issue  the  author  described  ED2,  his  public-domain  text 
editor.  Extensive  improvements  produced  RED,  including  new  buffer  routines 
which  remove  all  restrictions  on  the  size  of  files  which  may  be  edited.  This  month 
the  author  discusses  those  virtual  memory  routines,  and  a  code-saving  method  of 
error  recovery.  The  rest  of  RED  will  be  discussed  next  month. 

65  Anatomy  of  a  Digital  Vector  and  Curve  Generator 

by  Richard  Shiftman 

In  past  issues  we  have  presented  various  methods  for  drawing  lines  and  circles. 
This  article  presents  a  slightly  different  angle,  providing  BASIC  implementations 
of  both  a  vector  and  circle  generator. 

70  Fast  Matrix  Operations  in  Forth,  Part  II 

by  Steven  A.  Ruzinsky 

In  the  June  issue,  Part  I  of  this  series  presented  a  matrix-defining  word  and  a  few 
accessories.  This  installment  introduces  programs  for  performing  matrix  opera¬ 
tions,  as  well  as  some  more  advanced  accessories. 


DEPARTMENTS - 

6  Letters 
6  Editorial 

80  Dr.  Dobb's  Clinic 

Two  Gets  You  Ten,  Cheap  Thrills 
Dept.,  and  the  AGGHHH!  Program 

86  CP/M  Exchange 

MBOOT  Revisited,  CP/M  Plus  Feed¬ 


back,  a  bit  on  CCP  replacements, 
and  64K  and  Beyond 

92  1 6-  Bit  Software  Toolbox 

MS-DOS  Rebuttal,  68000  Tools, 
and  Sizing  Memory  on  the  IBM  PC 

100  Of  Interest 


Dr.  Dobb’s  Journal  (USPS  307690)  is  published  twelve  times  per  year  by  People’s  Computer 
Company,  P.O.  Box  E,  Menlo  Park,  CA  94025.  Second  class  postage  paid  at  Menlo  Park,  California 
94025  and  additional  entry  points.  Address  correction  requested.  Postmaster:  send  form  3579  to 
Box  E,  Menlo  Park,  California  94025  •  415/323-3111 


Dr,  Dobb’s  Journal,  Number  81,  July  1983 


5 


LETTERS 


Dr.  Dobb’s  Journal  welcomes  letters  to 
the  editor  as  a  forum  for  ideas,  innova¬ 
tions,  irascibility  and  even  idiosyncrasies. 
Some  letters  may  be  edited  for  clarity 
and  brevity.  The  Doctor  likes  hearing 
from  you  -  keep  on  writing! 

Catching  Bugs  in  Small -C 

Dear  DDJ, 

May  I  again  borrow  your  pages  to 
point  out  a  few  bugs  in  Sinall-C  V2.0, 
and  offer  the  code  (see  page  9)  for  the 
missing  selection  operator? 

There  are  bugs  in  ‘peephole’  and 
‘pstr’  which  are  very  similar.  ‘Peephole’ 
—  the  section  of  code  (TAB  defined) 
which  substitutes  pop-push  sequences  for 
fetches  of  local  variables  —  should  be 
changed  to  test  for  a  trailing  ‘  \tXCHG;;  ’ 
rather  than  simply  ‘  XCHG;;  ’,  with  the 
obvious  change  to  the  offset  in  the  stag¬ 
ing  buffer.  If  this  is  not  done,  the  NULL 
(which  marks  the  end  of  the  current  out¬ 
put  string)  might  be  skipped.  In  ‘pstr’, 
change  ‘++lptr’  to  ‘gch()’  to  force  an 
update  of  ‘ch’;  otherwise  the  NULL 
marking  the  end  of  the  current  input  line 
will  be  skipped  if  the  end  of  the  line  in  a 
multi-line  expression  is  a  character  con¬ 
stant.  This  results  in  the  trailing  end  of  a 
longer  previous  line’s  being  appended  to 
the  current  line.  . 


I  am  indebted  to  Mr.  M.  Grundy  for 
pointing  out  this  second  bug. 

A  further  bug  lies  in  wait  for  the  un¬ 
wary  in  the  function  ‘declloc’.  As  the 
code  stands,  one  must  declare  automatic 
pointers  as  ‘  *ptr’  rather  than  ‘ptr  [  ]  ’  since 
no  space  is  allocated  on  the  stack  for  this 
second  form.  The  fix  is  to  change  the 
‘else’  clause  of  the  test  ‘if  (k=needsub())’ 
to  a  compound  statement  by  adding  ‘k  = 
BPW;  ’  and  the  enclosing  braces. 

In  the  evaluation  of  expressions,  the 
comma  operator  is  not  fully  implemented. 
The  expression 

i  =  (j  =  k  ,1) 

should  result  in  the  j  being  assigned  the 
value  of  k,  and  i  the  value  of  1.  What 
actually  happens  is  that  the  value  of  k  is 
assigned  to  both  i  and  j,  and  the  ‘missing 
token’  error  is  generated  after  k.  For  a 
correction  (using  the  features  of  the  V2.0 
compiler)  locate  the  function  ‘primary’ 
(in  CC32.C)  and  insert  the  marked  lines: 

if  (  match  (“(”)) 

4 

#  do 

k  =  heir  1  (  1  val  ) ; 

#  while  (  match  (“,”)  ); 
needtoken  (“)”); 
return  k ; 

Y> 


There  is  a  further  minor  bug  —  more 
in  terms  of  style  error  —  which  users  of 
Small-C  may  become  prone  to.  The  old 
forms  of  the  assignment  operators  are  not 
tested  for: 

•=*=/=%  =+=_=«=»=-'=  |  =&’ 
Most  of  these  will  cause  no  problems  on 
on  transfer  to  a  full  system,  but  three  are 
obviously  ambiguous  (i.e.,  ‘=*  =&  =-’). 
The  UNIX  compiler  generates  warnings 
for  these  forms;  and,  for  “=+’  it  parses 
all  four  as  assignment  operators.  The 
Small-C  compiler  requires  some  editing 
to  check  for  these. 

I  offer  the  code  for  that  most  useful 
of  ‘C  ’  operators  —  the  selection  operator 
—  with  one  caveat:  the  code  as  presented 
conforms  to  normal  practice  on  if-else 
binding,  albeit  an  implied  else  in  this  case. 
The  result  does  not  parse  in  the  same  way 
as  the  C  compiler  on  the  UNIX  system. 
Whereas  I  may  write: 

x  ?  y  ?  xandy  :  xandnoty  :  notx 
the  UNIX  compiler  requires  explicit 
bracketing  thus: 

x  ?  (  y  ?  xandy  :  xandnoty  )  :  notx 

The  ‘bible’  (Kernighan  &  Ritchie) 
does  not  resolve  which  of  these  two  is  the 
correct  implementation.  I  believe  my 
approach  conforms  better  to  the  rest  of 
the  language  with  the  re-entrancy  at  each 


EDITORIAL 


Since  its  inception  DDJ  has  been  associated  with  a 
remarkable  group  of  people:  that  rather  diverse  group 
dedicated  to  the  proliferation  of  public  domain  software. 
These  people  freely  share  their  labors  with  the  rest  of  the 
computing  community,  providing  a  pool  of  ideas  which  the 
community  at  large  may  use,  develop,  and  refine.  Ultimate¬ 
ly  this  benefits  even  the  consumer  of  commercial  products. 
Indeed,  over  the  years  this  resource  has  been  a  significant 
factor  in  the  general  improvement  of  software. 

Their  approach  to  software  distribution  and  develop¬ 
ment  is  not  without  its  problems,  however.  When  one 
releases  rights  in  a  piece  of  work,  he  or  she  also  relinquishes 
the  corresponding  ability  to  regulate  how  that  work  is 
changed  or  used.  Lately,  we  seem  to  be  hearing  more  about 
bad  experiences  in  this  respect.  One  instance  may  be  found 
in  our  Letters  column  this  month.  Distribution  of  programs 
without  credit  to  the  author  is  just  one  more  example. 
None  of  the  problems  are  new,  but  they  are  not  likely  to 
become  less  prevalent  as  the  use  of  computers  and  the 
competition  in  the  software  market  increase. 

The  source  of  these  problems  lies  in  the  very  nature 


of  the  public  domain.  External  restraints  would  undermine 
the  benefits  currently  enjoyed,  and  result  in  increased  time 
and  cost  for  inforcement.  The  public  domain  offers  few 
legal  controls  to  authors,  but  also  few  restrictions.  Some 
degree  of  frustration  probably  must  be  endured  in  the  name 
of  the  cause,  relying  instead  on  individuals  to  exhibit  a 
sense  of  mutual  respect.  Due  to  DDJ' s  involvement  here,  we 
would  like  to  invite  discussion  from  readers  on  possible 
solutions  to  the  inherent  problems. 

Keep  in  mind  that  it  is  the  sense  of  community,  as 
much  as  anything,  that  has  kept  public  domain  software 
growing  over  the  years.  Often  the  only  compensation  which 
these  authors  receive  for  their  work  is  recognition  from 
their  peers.  Let  them  know  you  appreciate  their  efforts. 
Give  credit  when  you  use  their  material.  Better  still,  write 
to  them  with  your  comments  and  examples  of  what  you 
have  done;  perhaps  ask  them  for  feedback.  Allow  them  the 
satisfaction  of  seeing  their  influence. 


Reynold  Wiggins 
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level  of  precedence,  which  can  be  seen  in 
the  code  for  the  Small-C  compiler.  Perhaps 
the  good  Doctor  could  obtain  a  ruling? 
For  compatibility  substitute  ‘heir 3’  for 
‘heir2’  in  the  lines  marked  with  a  *#’  on 
the  enclosed  listing. 

Yours  sincerely, 

Andrew  Macpherson 
29  Tisbury  Road,  Apt.  7 
HOVE,  E.  Sussex 
England  BN3  3BJ. 

In  Defense  of  Ada 

Dear  Editor, 

Being  the  author  of  Supersoft  Ada,  I 
was  interested  in  the  article  by  Ed  Mitchell 
on  his  “Ada-oid”  Augusta.  I  would  like 
to  add  a  few  of  my  own  comments  to 
those  already  submitted. 

On  page  34  of  DDJ  No.  77,  Ed  lists 


results  of  the  benchmark  program  found 
in  an  earlier  Byte  magazine.  The  results, 
for  my  Ada  at  least,  are  incorrect.  The 
latest  version  of  the  compiler  executes  the 
program  in  37  seconds,  with  a  compile/ 
load  time  of  41  seconds.  The  Byte  article 
states  that  the  latest  available  versions 
were  used  for  the  test,  but  I  have  never 
been  able  to  get  the  benchmark  to  run 
that  slow  in  any  version.  This  is,  of  course, 
not  Ed  Mitchell’s  fault. 

I  have  noted  several  letters  appearing 
in  DDJ  and  other  publications  with  dis¬ 
may;  Ada  does  not  seem  to  be  a  popular 
language  among  the  microcomputer 
community.  Considering  Pascal’s  wide 
acceptance,  and  Ada’s  similarity  to  Pascal 
(which  is  not  a  coincidence),  1  am  at  a 
loss  to  explain  the  evident  lack  of  support 
for  the  new  language.  I  for  one  would  like 
to  come  to  its  defense  (no  pun  intended). 

First,  let  me  point  out  that  I  am  not 


Listing  —  Selection  Operator 

Selection  operator,  new  function  82-12-16,  A. Macpherson . 
selector  ?  exprl  :  expr2 


heir2  (  lval  ) 


k ; 

k  =  plungel  (  heir3,  lval  ); 
if  (  match  ("?")  ) 

4 

int  falselab,  endlab,  val; 

char  reg2used,  selconst,  explconst, 

sel  2 ; 

falselab  =  getlabel  ( ) ; 

reg2used  =  0; 

if  (k)  rvalue  (  lval  ); 


return  k; 


if  (selconst  =  lval  13])  /*  selector  is  a 

constant  */ 

4 

if(sel2  =  >lval[4])  jump( falselab) ; 

> 

else  4 

testjump  (falselab); 
reg2used  =  lval  (  5  ]  ; 

)> 

dropout  (  plungel  (heir2,  lval),  jump, 
endlab  =  getlabel  (),  lval  ); 

if  (explconst  =  lval  [3])  val  =  lval [4]; 

else  reg2used  |=  lval[5]; 

postlabel  (  falselab  ) ; 
needtoken  (":"); 

if  (  plungel  (heir2,  lval))  rvalue(  lval  ); 
if  (  lval  [3]) 

4 

const  ( lval  [ 4 ]  )  ; 
if  (selconst  &&  sel2) 

val  =  lval  [  4 ]  ; 

}> 

else  reg2used  |=  lval[5]; 
lval  [  5  ]  =  reg2used; 
lval  [  4  ]=  val; 

lval  [  3  ]  =  selconst  &&  ((!sel2  &&  explconst) 
|  |  (  sel 2  &&  lval  [3]  )  )  ; 

postlabel  (  endlab  ); 
return  0; 

> 


an  Ada  fanatic.  I  enjoy  programming  in 
Ada  as  much  as  I  do  in  any  language,  in¬ 
cluding  Pascal,  C,  and  yes,  even  BASIC. 
Ada  has  much  to  offer  a  programmer  for 
some  applications.  I  wouldn’t  try  to  write 
a  text-oriented  editor  in  it,  it  has  lousy 
string  handling  capabilities;  but  then  I 
wouldn’t  try  to  write  a  tax  program  in 
LISP,  or  an  adventure  game  in  COBOL. 
The  DoD  wanted  a  language  to  write 
programs  for  embedded  systems  such  as 
guided  missiles.  The  language  they  ended 
up  with  just  so  happens  to  be  a  good 
structured  language  that  is  also  useful  for 
general  scientific  programming.  A  pro¬ 
grammer  who  is  intelligent  enough  to  be 
able  to  select  the  proper  language  for  a 
given  application,  whether  he  likes  pro¬ 
gramming  in  that  language  or  not,  is 
indeed  a  valuable  asset. 

The  language  has  its  faults.  Operator 
overloading  certainly  won’t  make  a  pro¬ 
gram  more  readable  or  maintainable,  the 
I/O  stinks,  and  most  people  think  that 
Ada  tried  to  bite  off  more  than  it  could 
chew.  Nevertheless,  one  fact  remains:  the 
government  is  backing  Ada  100%  and  you 
can  bet  that  good  Ada  programmers  will 
soon  be  in  demand. 

Ada  does  have  its  strong  points.  It  is 
a  strongly  typed  language,  a  characteristic 
well  received  by  programmers  as  shown 
by  Pascal.  It  has  better  structure  than  Pas¬ 
cal,  solving  the  “dangling-else”  problem. 
Resulting  code  is  much  easier  to  read,  and 
the  flow  of  control  easier  to  see  in  an  Ada 
program.  Ada  has  a  powerful  set  of  basic 
statements,  and  its  packaging  facilities 
and  multi-tasking  capabilities  are  relative¬ 
ly  new  concepts  being  introduced  in  a 
single  language.  Corporations  such  as 
Honeywell,  SofTech,  and  Western  Digital 
have  invested  significant  effort  in  their 
respective  Ada  projects. 

The  discussion  of  Ada  might  not  have 
been  even  brought  up  if  Ed  had  called  the 
language  “STRUCT-1,”  or  “NEWPAS,” 
or  something  like  that.  I  am  of  course 
referring  to  the  DoD’s  Boolean  logic 
concerning  Ada  compilers.  Augusta  bears 
less  of  a  resemblance  to  Ada  than  one 
might  think.  The  implementation  looks 
more  like  a  language  oriented  toward 
graduate  courses  in  structured  language 
design:  a  “compiler-writer’s  language”  so 
to  speak.  I  am  not  saying  I  approve  of  the 
DoD’s  position;  I  think  that,  if  they  ap¬ 
proved  subsets,  the  acceptance  of  Ada 
would  be  more  widespread.  Let  me  point 
out  that  I  stated  SUBSETS,  not  “variants 
on  the  Ada  language  with  extensions.” 
Also,  I  am  not  trying  to  put  down  Ed’s 
work.  I  know  the  difficulties  in  implement¬ 
ing  a  structured  language  and  1  applaud 
his  success. 

Count  me  as  one  of  the  supporters 
of  the  Ada  language.  I  welcome  any  com¬ 
ments  or  suggestions  sent  to  my  address; 
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or  you  may  leave  CompuServe  correspon¬ 
dence  at  71705,2037.  Thank  you. 
Sincerely, 

David  C.  Norris 
Maranatha  Software  Systems 
500  Catalina  Road,  No.  305 
Cocoa  Beach,  FL  32931 

Public  Domain  Responsibilities 

To  DDJ  Readers  and  CF/M  Users, 

Over  the  years  that  DDJ  has  been 
serving  us,  I  have  contributed  one  article 
(a  disassembler  in  issue  no.  27),  a  review 
of  the  PC-1  pocket  computer  (in  issue 
no.  52)  and  a  few  letters.  However,  this 
contribution  is  a  bit  different.  The  bot¬ 
tom  line  of  this  letter  is  a  warning! 

1  am  the  author  of  a  set  of  programs 
which  are  in  widespread  public  domain 
distribution  (at  least  three  continents). 
They  are  called  SQ.COM,  USQ.COM,  and 
FLS.COM.  They  run  on  CP/M  systems 
and  serve  to  squeeze  files  to  smaller  sizes 
in  preparation  for  transmission  via  modem 
or  distribution  via  diskette. 

The  latest  versions  of  these  programs 
are  1.5,  1.5  and  1.1,  respectively.  I  released 
these  programs  to  the  public  domain,  ex¬ 
cept  for  financial  gain,  and  included  full 
source  code  (in  C  language)  and  extensive 
documentation.  This  software  is  now 
available  via  the  C  Users  group,  which  has 
advertised  in  DDJ. 

Having  had  reasonable  experiences 
with  previous  public  offerings,  I  gave  my 
name  and  address  in  the  documentation 
and  in  the  sign-on  message  of  each  pro¬ 
gram.  Therein  lies  the  story ! 

In  recent  months  1  have  had  a  couple 
of  dozen  phone  calls  claiming  that  these 
programs  have  destroyed  various  innocent 
files.  But  when  1  ask  for  details,  I  find 
that  the  programs  in  question  have  ver¬ 
sion  numbers  higher  than  any  I  have  ever 
issued!  Not  only  that,  but  many  different 
version  numbers,  as  high  as  1.9,  have  been 
mentioned ! 

I  expect  that  whoever  produced  each 
version  of  these  programs  was  as  innocent 
as  I  was  in  August  of  1981  when  I  issued 
the  above-mentioned  programs.  But  the 
fact  remains  that  one  or  more  persons  has 
taken  it  upon  themselves  to  propagate 
modified  versions  of  my  software  without 
taking  the  responsibility  of  adding  their 
name  and  address  to  the  documentation 
and  sign-on  messages. 

It  is  an  unfortunate  fact  that  C  and 
probably  other  high-level  languages  can 
crash  impolitely  when  the  CP/M  TPA  is 
too  small  for  the  program  and  its  data 
space,  including  dynamically  allocated 
local  variables.  (These  programs  do  use 
recursive  algorithms.) 

I  have  heard,  without  confirmation, 
that  vast  amounts  of  code  have  been  added 
to  some  versions  of  these  programs  to  add 
wild  card  file  name  processing.  Perhaps  this 


is  the  problem.  I  provided  that  feature  as 
a  separate  program,  FLS.COM,  precisely 
for  that  reason.  It  is  also  possible  that  full 
and  careful  use  of  the  recompilation  op¬ 
tions  available  in  BDS-C  has  been  abused, 
resulting  in  too  much  code  or  improperly 
linked  code.  Or  maybe  there  have  simply 
been  some  accidents  in  copying  or 
modem  transmission. 

Whatever  the  case,  I  recommend  that 
if  you  modify  software  which  you  have 
not  written,  then  try  to  consult  with  the 
original  author  before  publicly  distribut¬ 
ing  such  software.  If  that  is  not  possible, 
at  least  accept  the  responsibility  of  being 
the  first  line  of  complaint  handling  by 
adding  (not  replacing)  your  name  to  the 
documentation  and  sign-on  message. 

If  anyone  has  a  file  which  the  above- 
mentioned  versions  of  my  programs  can¬ 
not  squeeze  and  then  reproduce,  please 
contact  me.  My  computers  can  read  and 
write  the  following  diskette  formats: 
Micropolis  Mod  II,  Lobo  Max-80  5” 
40  track/side  (SS/DS,  SD/DD)  formats, 
Osborne  Single  Density,  Omikron  5” 
single  density,  Xerox  5”  single  density. 
Except  for  the  Micropolis,  all  of  the 
above  are  handled  by  my  Lobo  Max-80 
computer. 

Do  you  really  want  more  public 
domain  source  code  software?  If  so,  and 
if  you  know  the  source  of  these  modifi¬ 
cations,  please  help  stamp  out  the  bad 
versions  (copies?)  of  this  software.  Un¬ 
fortunately,  I  don’t  know  exactly  which 
versions  are  bad  because  not  one  single 
person  has  ever  sent  me  a  courtesy  copy 
of  any  modifications ! 

To  those  bewildered  innocent  victims, 
the  unsqueezing  process  contains  a  valid¬ 
ity  check  based  on  the  original  file.  If  you 
can  produce  a  file  (not  just  a  console  dis¬ 
play)  by  running  the  USQ.COM  program, 
then  the  resulting  file  should  be  an  exact 
replica  of  the  original. 

I  also  ask  purchasers  of  communica¬ 
tions  packages  who  I  have  authorized  to 
distribute  this  software  not  to  assume 
that  I  am  responsible  for  the  communica¬ 
tions  packages.  It  seems  that  reproduction 
of  my  documentation  files  makes  my 
name  and  address  more  prominent  than 
those  of  the  commercial  distributers ! 

Sincerely, 

Richard  Greenlaw 
251  Colony  Ct. 

Gahanna,  Ohio  43230 


Moaning  &  Groaning 
About  MS-DOS 

Dear  Dr.  Dobb, 

I  have  to  take  issue  with  Jim  Howell’s 
comments  regarding  the  MS-DOS  batch 
facility  ( DDJ  No.  79,  16-Bit  Software 
Toolbox).  But  more  of  that  later. 


Over  the  past  few  months,  I  have 
been  improving  various  CP/M -80  v.2.2 
utilities  to  be  the  standards  I  have  been 
used  to  on  ISIS  systems.  One  of  thesejobs 
involved  upgrading  SUBMIT  to  handle 
multiple  batch  files  and  nested  batch 
files.  In  this,  various  issues  of  DDJ  have 
proven  themselves  more  than  useful,  for 
which  many  thanks.  I  have  one  remaining 
task  to  perform  which  I  think  should  be 
relatively  simple  but  may  interest  other 
readers.  1  wish  to  halt  the  execution  of  a 
batch  running  under  XSUB  after  the  com¬ 
mand  line  has  been  read  but  before  it  is 
executed.  I  then  wish  to  perform  an 
acceptance  of  the  command  by  hitting 
return  or  to  cancel  it  with  a  control-x. 
Probably  the  easiest  solution  would  be  to 
write  a  small  program  to  do  this,  but  I 
am  intrigued  with  the  idea  of  modifying 
XSUB. 

Now,  turning  to  the  point  of  conten¬ 
tion  with  Mr.  Howell,  the  above  task  was 
relatively  easy  to  perform  using  DDT.  (In 
fact  I  disassembled  SUBMIT  and  XSUB 
and  proceeded  that  way.)  When  I  came  to 
try  the  same  job  on  the  MS-DOS  batch 
facility,  it  has  so  far  proved  impossible 
as  the  “SUBMIT-equivalent”  is  buried 
somewhere  in  the  DOS  code.  Further, 
there  seems  to  be  no  “XSUB-equivalent” 
allowing  called  programs  to  accept  input 
from  the  batch  rather  than  the  keyboard. 
In  these  regards,  I  find  the  MS-DOS 
batch  facility  to  be  much  inferior  to  the 
DRI  product. 

A  final  moan  and  groan  about  MS- 
DOS,  or  at  least  about  IBM’s  packaging 
of  Microsoft’s  software:  I  purchased  the 
IBM  MACRO  ASSEMBLER  only  to  find 
later  that  I  have  to  also  purchase  a  high- 
level  language  compiler  to  get  a  library 
manager  utility.  I  wonder  if  the  people 
who  package  these  products  ever  use 
them  themselves.  Also,  the  Microsoft  bro¬ 
chure  on  MS-DOS  mentions  a  TRANS 
utility  for  translating  MACRO-80  source 
code  into  MACRO-86  source.  Has  any¬ 
body  out  there  seen  this  utility  —  it  seems 
to  be  impossible  to  obtain. 

Lastly,  much  praise  and  thanks  to 
you  and  all  the  individuals  for  all  the  use¬ 
ful  articles  on  Small-C. 

Sincerely, 

Bill  Potter 

425  Fair  Drive,  No.  205 

Costa  Mesa,  CA  92626 


Still  Searching  for  The  Right  Byte 

Gentlem  en: 

I  have  just  finished  reading  the  excel¬ 
lent  article  in  DDJ,  No.  78,  regarding  the 
disk  parameter  block  by  Gene  Head  in 
“CP/M  Exchange.”  It  came  just  in  time 
to  prevent  my  going  to  the  insane  asylum. 

(Continued  on  page  105) 
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AUGUSTA,  Part  IV 

The  Augusta  Compiler  (continued) 


Edward  Mitchell  began  this  series  in  Jan¬ 
uary  of  this  year.  Due  to  the  size  of  Ada, 
Augusta  was  intended  to  be  a  (very)  tiny 
language  in  the  spirit  of  languages  such  as 
Tiny  BASIC,  Tiny  Pascal  and  Small-C. 
During  the  ensuing  months  he  has  pre¬ 
sented  an  in-depth  look  at  the  structure 
and  implementation  of  Augusta,  intend¬ 
ing  to  illustrate  how  to  build  such  a 
language.  Regardless  of  philosophical 
differences  one  may  have  with  the  author 
concerning  language  implementations, 
the  discussion  is  bound  to  have  been 
stimulating. 


Part  IV  concludes  the  series  by  de¬ 
scribing  the  internal  operation  of 
the  Augusta  compiler.  Also  in  this 
discussion  are  details  of  the  lexical 
analyzer,  symbol  table,  code  generation, 
and  backpatching  techniques,  plus  some 
personal  comments  on  Ada,  Microsoft 
BASIC,  and  the  overall  development  of 
the  compiler. 

General  Features 

Microsoft  BASIC,  like  most  BASICS, 
lacks  constant  symbol  declarations.  Be¬ 
cause  of  that,  a  large  number  of  BASIC 
“variables”  are  used  in  the  compiler  as 
“constants.”  For  example,  all  of  the  p- 
codes  generated  by  Augusta  are  labelled 
with  mnemonic  variable  names.  Rather 
than  generate  “  1  ”  for  the  LDCI  opcode, 
it  is  much  clearer  to  refer  to  PLDCI 
which  always  has  the  value  1 . 

Similarly,  whenever  the  lexical  ana¬ 
lyzer  sees  a  keyword,  it  returns  an  integer 
that  uniquely  identifies  that  keyword.  As 
described  in  the  next  section,  each  call 
to  the  scanner  sets  variable  T  equal  to 
an  integer  that  represents  the  token.  For 
example,  BEGIN  sets  T=KBEGIN,  where 
KBEGIN  is  an  integer  constant.  There¬ 
after,  if  the  parser  is  expecting  a  BEGIN 
statement,  it  can  test  by 
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IF  T= KBEGIN  THEN  .  .  . 

Comparing  integers  is  much  faster  than 
comparing  strings  (e.g.,  comparing  T$  = 
“BEGIN”  is  slow).  Punctuation  symbols, 
like  “(”  “+”,  and  are  also  repre¬ 
sented  as  integers.  Lines  1130  through 
1210  of  the  compiler  (see  Listing  Two  of 
“Augusta,  Part  III,”  page  20,  DDJ  No.  79, 
May  1983)  initialize  these  “constant” 
variables.  Note  that  all  variables  inside  the 
compiler  are  integers  unless  explicitly 
labelled  as  some  other  type. 

The  variable  names  are  mnemonics 
for  the  tokens  they  represent.  SQUOTE  is 
a  single  quote,  C  is  a  constant,  LP  is  a  left 
parenthesis,  and  RP  a  right  parenthesis. 
MUL,  DIV,  ADD,  and  SUBT  correspond 
to  the  arithmetic  operators  “/”, 

“+”,  and  LES,  LEQ,  EQ  and  so 
on  refer  to  the  relational  operators  “<  ”, 
“<=”,  and  “=”.  ID  is  an  identifier  and 
CH  a  character  constant.  SC  is  a  string 
constant.  The  rest  of  the  tokens  should 
be  apparent  from  their  “constant”  names. 

The  compiler  is  organized  into  nu¬ 
merous  subroutines,  each  identified  by  a 
comment  on  the  first  line  of  the  routine. 
Table  1  (page  20)  is  a  cross  reference  of 
the  major  subroutines  and  their  location 
and  function.  Table  2  (page  21)  is  a  dic¬ 
tionary  of  major  variables  in  the  compiler. 
Many  subroutines  take  their  names  direct¬ 
ly  from  the  boxes  shown  in  the  syntax 
diagrams  in  Part  I  (DDJ  No.  75,  January 
1983).  For  example,  the  routine  labelled 
SEQOFSTMTS  corresponds  to  the  block 
in  the  syntax  diagram  labelled  SEQ  OF 
STMTS  (see  pages  24-25  of  the  January 
issue). 


Compiler  Initialization 

All  of  the  keywords  and  predefined 
procedure  names  are  kept  in  a  data  file 
titled  “KEYWORDS.TXT”  (see  Listing  2, 
page  32).  When  run,  the  compiler  opens 
the  file  and  reads  in  the  identifiers. 

Keywords  are  stored  in  a  fast  look-up 
table,  array  KEY$(),  hashed  by  the  key¬ 
word’s  first  letter.  The  first  letter  (“A”=l, 
“B”=2,  “C”=3,  etc.)  indexes  an  array 
MAP(i).  MAP(i)  is  essentially  a  hash 
function,  pointing  directly  to  the  set  of 
keywords  beginning  with  that  letter. 
MAP(l)  is  the  index  in  KEY$(j)  of  the 
keywords  beginning  with  “A”.  Map  (2) 
points  to  the  keywords  beginning  with 
“B”  and  so  on.  The  lexical  analyzer  uses 
the  hash  table  to  quickly  identify  key¬ 
word  symbols. 


The  Lexical  Analyzer 

When  the  parser  needs  a  token,  it 
calls  the  subroutine  at  line  1400  labelled 
“GETSYM.”  GETSYM  examines  the 
character  that  the  scanner  last  read  (in 
CHS)  and  branches  to  the  appropriate 
state.  For  example,  if  the  character  is  an 
“A”,  “B”,  “C”  ...  ,  or  “Z”,  then  the 
analyzer  jumps  to  line  1460  and  reads  an 
identifier.  If  the  character  is  a  digit,  then 
it  jumps  to  line  1490  where  it  scans  for 
an  integer. 

The  lexical  analyzer  is  initialized  by 
calling  GETLINE,  which  inputs  a  line  of 
the  Augusta  source  program  into  BUF$. 
GETLINE  then  tacks  an  “end-of-line” 
marker  onto  BUF$  and  skips  over  any 
leading  blanks.  It  then  sets  CHS  equal  to 
the  first  “real”  character  in  the  line  and 
sets  B  to  be  the  index  in  BUFS  of  the 
next  character. 

GETSYM  looks  at  the  character  in 
CHS  and  processes  it  accordingly.  As 
GETSYM  needs  additional  characters  it 
calls  GETCH,  which  sets  CHS  to  the 
character  at  position  B  and  increments  B. 
When  GETSYM  detects  the  “end-of-line” 
marker  it  calls  GETLINE  to  read  in  the 
next  line  from  the  source  file. 

GETSYM  sets  variable  T  equal  to  the 
integer  representation  of  the  token.  Where 
needed,  S$  holds  the  actual  token  string. 
TT$  is  set  to  CHR$(T)  and  is  used  in  con¬ 
junction  with  the  BASIC  INSTR  function 
to  quickly  check  if  T  is  a  member  of  a  set 
of  tokens.  For  example,  RELOPSS  is  a 
string  containing  all  of  the  token  values 
for  relations  (e.g.,  “=”,  “<=”,  etc.).  The 
parser  can  quickly  determine  that  T  is  a 
relational  operator  by  checking  to  see 
that  INSTR(RELOPS$,  TT$)  is  greater 
than  zero. 


The  Symbol  Table 

As  the  source  program  is  parsed,  the 
compiler  needs  to  keep  track  of  the  varia¬ 
bles  and  procedure  names  that  have  been 
defined.  Several  techniques  can  be  used 
to  manage  a  symbol  table.  Binary  trees, 
hashing,  or  ordered  tables  come  to  mind. 
But  it  turns  out,  at  least  in  interpretive 
BASIC,  that  the  better  methods  are 
quite  slow. 

Searching  a  string  or  strings  in  a 
sequential  manner  using  the  INSTR  func¬ 
tion  is  much  faster  than  a  binary  search 
written  in  BASIC.  This  observation  applies 
to  fairly  large  tables  as  well.  Consequently, 
Augusta’s  symbol  table  uses  a  stack-like 
mechanism  which  is  then  searched  sequen- 
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tially  by  scanning  it  with  INSTR. 

As  symbols  are  encountered  while 
parsing  the  program  they  are  placed  onto 
the  top  of  the  stack.  As  shown  in  Figure 
1  (page  16),  the  symbols  for  procedure 
P2  are  placed  on  the  stack  so  that  the 
most  recently  defined  symbol  is  on  top. 
Searches  for  a  particular  identifier  always 
begin  at  the  top  of  the  stack.  Consequent¬ 
ly,  the  most  recently  defined  syrnbols, 
such  as  local  identifiers,  are  encountered 
first.  And  since  most  searches  are  for 
local  variables,  the  search  terminates 
fairly  quickly. 

Rather  than  using  an  actual  stack,  a 
string  variable  is  used  to  hold  the  symbol 
table.  The  first  symbol  encountered  is 
placed  in  S$.  The  second  symbol  is 
inserted  into  the  front  of  S$  as, 

S$  =  IDS  +  SS 

Therefore,  if  two  variables  are  defined  in 
a  program  as, 

I  : INTEGER; 

J  : INTEGER; 

then  S$  is  “J  I”,  with  J  before  I  in  the 
table.  The  table  is  then  searched  left  to 
right  by  executing, 

1NSTR(  S$,  IDS) 

where  IDS  is  an  identifier  to  look  up. 
This  means  that  if  a  second  variable  I  is 
defined  locally  to  a  subsequent  procedure 
it  will  get  placed  before  the  other  I  in  S$. 
Then,  when  INSTR  is  used  to  search  SS, 
the  most  recent  definition  of  I  is  found 
first. 

There  is  a  problem  with  this  scheme: 
in  Microsoft  BASIC,  strings  cannot  be 
longer  than  255  bytes.  The  solution  is  to 
maintain  an  array  of  strings  SS ( 1 ),  SS ( 2 ), 

S$(3) . When  S$(l)  is  about  to 

exceed  255  bytes  in  length,  S$(2)  gets 
used.  When  SS ( 2 )  fills  up,  S$(3)  is  used. 
The  strings  are  then  searched  by  first 
looking  at  SS (3 ),  then  S$(2)  and  finally 
S$(l).  The  subroutines  at  lines  3850  and 
3890  (see  Listing  1,  page  22)  add  symbols 
to  the  stack  and  perform  searches,  respec¬ 
tively.  Figure  2  (page  17)  shows  the  de¬ 
tailed  layout  of  a  single  17-byte  symbol 
table  entry. 

Because  the  symbol  table  is  a  stack, 
the  compiler  cannot  do  type  checking  of 
procedure  parameters.  After  the  proce¬ 
dure  is  compiled,  the  local  and  parameter 
variables  are  removed  from  the  stack, 
leaving  only  the  procedure’s  name.  Doing 
this  substantially  reduces  the  symbol 
table’s  memory  requirements. 

When  the  compiler  parses  a  procedure 
call  like, 

SEARCH  (  ELEMENT,  ©FOUND  ); 

the  symbol  table  no  longer  contains  the 
list  of  parameters  originally  defined  for 
SEARCH.  Because  of  that,  the  compiler 
cannot  detect  type  mismatches  between 
the  actual  parameters  and  the  parameter 
variables.  Nor  can  it  detect  whether  the 


correct  number  of  parameters  was  used. 
In  addition,  the  special  symbol  is 

needed  to  tell  the  compiler  when  to  pass 
a  parameter  by  reference. 

The  Parser 

Recursive -descent  parsers,  like  the 
one  used  in  Augusta,  were  described  in 
detail  in  Part  III.  Since  Augusta  is  written 
in  BASIC,  recursive-descent  parsing  re¬ 
quires  extra  code  to  handle  recursive  sub¬ 
routine  calls  and  the  saving  of  data  onto 
an  internal  stack. 

For  example,  the  CASE  statement 
may  itself  contain  other  CASE  statements 
as  part  of  the  code  executed  for  the  vari¬ 
ous  conditions.  When  that  happens,  the 
same  subroutine  is  entered  twice  —  once 
to  begin  parsing  the  outer  CASE  state¬ 
ment,  and  the  second  time  to  parse  the 
inner  CASE  statement.  All  variables  that 
are  unique  to  each  CASE  must  be  pre¬ 
served  by  pushing  them  onto  an  internal 
stack.  Upon  return  from  processing  the 
second  (or  third,  or  fourth,  .  .  .)  CASE, 
the  variables  are  restored  by  popping 
their  old  values  from  the  stack.  Other 
than  that,  the  parser  works  as  described 
last  month. 

The  compiler  uses  an  array  S()  as  a 
stack  and  variable  SP  as  the  stack  pointer. 
A  single  integer  X  is  pushed  onto  the 
stack  by  calling  the  PUSH  subroutine  at 
line  4280.  S(SP)  is  set  equal  to  X,  and  SP 
is  incremented  by  one.  Values  are  popped 
by  calling  the  POP  subroutine  at  line 
4300.  The  overall  size  of  the  stack  is  de¬ 
termined  by  the  DIM  S()  statement  in 
line  1790. 

Parsing  expressions  requires  the  com¬ 
piler  to  keep  track  of  the  “type”  of  the 
values  it  is  dealing  with.  When  trying  to 
add  two  values  together,  it  must  verify 
that  both  values  are  really  numbers,  and 
not  strings  or  characters.  The  array  TY() 
and  the  “Type  Stack  Pointer”  TSP  are 
used  to  perform  type  checking. 

The  code  for  parsing  expressions 
appears  in  the  subroutines  labelled  EXPR 
(line  3100),  RELATION  (line  3190),  SE 
(line  3290),  TERM  (line  3350),  and 
PRIMARY  (line  3610).  Compare  these 
routines  to  the  similarly  named  sections 
of  the  syntax  diagrams  shown  in  Part  I. 

Within  PRIMARY,  p-codes  are  gener¬ 
ated  to  load  the  values  of  variables  and 
constants  onto  the  run-time  stack.  When 
the  compiler  sees  a  constant,  such  as  the 
integer  517,  it  generates  an  instruction, 

LDCI  517 

Simultaneously,  it  places  a  type  marker 
on  the  type  stack  inside  the  compiler.  It 
pushes  the  type  TINT  (a  “constant”  varia¬ 
ble  that  is  mnemonic  for  “  Type  INTeger”) 
on  the  stack  TY(). 

Let’s  assume  that  the  statement 
being  parsed  contains 

I  :=  35  +  517; 


Upon  seeing  the  identifier  I  and  de¬ 
termining  that  it  is  an  integer  variable, 
Augusta  puts  a  TINT  on  the  TY()  stack. 
Next,  at  the  constant  35,  Augusta  again 
puts  TINT  on  the  stack.  The  same  occurs 
for  517.  There  are  now  three  integer  types 
on  the  type  stack.  Since  addition  can 
only  be  performed  on  integers,  the  com¬ 
piler  checks  that  the  top  two  values  on 
the  type  stack  are  both  integers.  Since 
they  are,  it  removes  both  TINTs  and 
generates  the  ADI  pseudo  code.  But  the 
result  of  ADI  is  an  integer,  so  it  puts  one 
TINT  back  on  the  stack.  Returning  to 
process  the  “I  :  =  ”  part  of  the  statement, 
the  compiler  insures  that  the  type  of  the 
expression  is  also  an  integer  since  it  is 
being  assigned  to  the  integer  variable  I. 

Type  checking  is  also  needed  to 
handle  relational  operators.  For  example, 
when  parsing  the  relation  SI  =  S2,  the 
compiler  needs  to  know  if  SI  and  S2  are 
strings  or  integers  since  it  generates  a  dif¬ 
ferent  p-code  depending  on  the  type  of 
the  relation  (EQUSTR  for  strings,  EQUI 
for  integers). 


Code  Generation 

Once  the  compiler  has  parsed  a 
portion  of  a  statement,  it  translates  the 
statement  into  pseudo  code.  Looking  to 
PRIMARY  at  line  3610,  we  can  see  how 
it  generates  the  “load  constant”  instruc¬ 
tions.  At  line  3630,  if  the  token  is  a  con¬ 
stant,  the  compiler  places  TINT  on  the 
type  stack  and  calls  the  subroutine  at 
line  3640. 

Whenever  GETSYM  reads  a  con¬ 
stant,  T  is  set  equal  to  the  C  token  and 
TN  is  set  to  the  corresponding  numeric 
value  of  the  token  (hence  the  mnemonic 
for  “Token  Number”).  At  line  3640  the 
compiler  generates  a  p-code  to  load  the 
value  of  TN  onto  the  p-machine’s  stack. 

The  compiler  must  choose  which  of 
the  various  “load  constant”  p-codes  is 
best  to  use.  IfTN  =  -l,  then  the  compiler 
generates  the  SLDCN1  (“Short  Load 
Constant  Negative  1  ”)  opcode.  If  TN’s 
value  is  from  0  to  15,  it  generates  one  of 
the  single-byte  short  loads  —  SL.DC0, 
SLDC1,  etc.  If  the  constant  is  greater 
than  15  but  less  than  256,  it  generates 
the  SLDC  “Short  Load,”  followed  by  the 
single-byte  constant  to  load.  Otherwise, 
the  compiler  emits  the  LDCI  “Load  Con¬ 
stant  Integer”  opcode  followed  by  the 
2-byte  constant. 

The  code  is  actually  output  by- 
setting  W  equal  to  the  opcode  value  (e.g., 
W  =  PLDCI )  and  calling  the  GENBYTE 
subroutine  at  line  3990.  The  variable  CP 
(“Code  Pointer”)  always  contains  the  ad¬ 
dress  where  the  next  byte  of  code  will  be 
written.  If  necessary,  an  immediately 
following  parameter  is  emitted  by  calling 
either  GENBYTE  or  GENWORD  as 
appropriate. 


14 
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The  actual  mechanism  by  which  the 
code  bytes  end  up  in  the  code  file  is  some¬ 
what  complicated.  First,  let’s  look  at  a 
simplified  version.  The  code  file  is  always 
kept  open  as  file  #1  with  a  record  size  of 
128  bytes.  The  current  file  buffer  is 
accessed  through  a  field  statement  that 
overlays  the  buffer.  For  example, 

FIELD  #1, 20  AS  D$,  1  AS  T$ 

places  T$  at  the  twenty-first  byte  in  the 
buffer.  To  output  a  byte,  the  compiler 
uses  CP,  the  code  address,  to  calculate 
which  record  in  the  code  file  will  hold  the 
code.  Then  it  computes  the  byte  offset 
within  the  record.  By  assigning, 


LSET  T$  =  CHR$(W) 

the  byte  is  written  to  the  code  file  buffer. 
CP  is  incremented  by  one  to  point  to  the 
next  byte. 

When  the  buffer  fills  up  to  128  bytes 
it  must  be  written  to  the  code  file  and  a 
new  buffer  prepared  for  additional  code. 
Conceptually,  you  can  think  of  the  code 
generation  working  like  this.  But  actually 
the  compiler  keeps  three  buffers  of  code 
in  memory  simultaneously.  It  does  this 
because  it  sometimes  has  to  “backpatch” 
code  that  has  already  been  generated  and 
it  is  much  faster  to  access  one  of  the  buf¬ 
fers  than  to  read  a  record  from  the  disk. 

Backpatching 

When  the  compiler  is  producing 
code,  it  sometimes  has  to  create  forward 
jumps  for  which  it  does  not  yet  know  the 
destination.  Part  III,  Listing  7  (page  29, 
DDJ  No.  79,  May  1983)  showed  the  p- 
codes  generated  for  an  IF-THEN-ELSE 
statement.  The  statement  following  THEN 
ends  with  an  unconditional  jump  (UJP 
p-code)  to  the  first  statement  following 
the  IF-THEN-ELSE.  When  the  compiler 
produces  the  UJP  instruction,  it  doesn’t 
know  where  the  jump  should  be  to. 
Instead  it  must  remember  the  location  of 
the  UJP  instruction,  and,  after  compiling 
the  following  statements,  go  back  and  fix 
them  up. 

In  many  instances,  there  are  numer¬ 
ous  UJP  and  FJP  instructions  that  must 
be  fixed  up.  A  clever  way  to  remember 
the  location  of  the  UJP  instructions  is  to 
link  them  together  into  a  list  using  the 
2  bytes  following  each  UJP.  A  variable 
LUJP  is  used  in  the  compiler  to  hold  the 
address  of  the  most  recent  UJP  instruc¬ 
tion.  The  address  field  of  the  UJP  instruc¬ 
tion  pointed  to  by  LUJP  points,  in  turn, 
to  the  previous  UJP  instruction.  In  that 
manner,  all  of  the  UJPs  are  linked  to¬ 
gether.  An  address  of  0  signifies  the  end 
of  the  UJP  list. 

Once  the  statements  have  been  com¬ 
piled,  Augusta  goes  back  along  the  chain 
of  UJP  instructions  and  changes  the  links 
to  be  offset  to  the  first  statement  follow¬ 
ing  the  ELSE. 


Error  Handling 

Augusta’s  ability  to  handle  syntax 
and  semantic  errors  is  limited.  Missing 
semicolons  cause  the  compiler  to  issue  a 
warning  and  then  to  continue  compiling 
the  text.  When  other  syntax  errors  are 
detected,  the  compiler  prints  an  error 
code  (see  Tables  2  and  3  on  page  21), 
the  source  line  containing  the  error,  and 
an  asterisk  “  *  ”  to  the  right  of  the  last 
token  read.  It  then  displays, 

REENTER  + 

You  may  then  type  in  the  remaining  por¬ 
tion  of  the  line  in  its  correct  form.  For 
example,  if  your  program  contains, 

IF  A=  B  THEN  PUTLINE  (“A=B”); 
END; 

Augusta  detects  the  missing  “IF”  after 
the  “END”  and  displays, 

39  EXPECTED 
ERROR  4 
END; 

* 

REENTER  +  IF; 

At  the  “REENTER”  prompt,  the  IFj  is 
entered. 

Semantic  errors  such  as  undeclared 
identifiers  cause  the  compiler  to  print  the 


above  error  message  and  then  halt.  Multi¬ 
ply  defined  identifiers  are  ignored  —  only 
the  most  recent  definition  is  used. 


Other  Features 

Augusta  does  not  place  a  Emit  on 
the  length  of  a  procedure  or  a  program. 
However,  since  the  compiler  is  written  in 
BASIC  using  16 -bit  integer  addresses, 
there  is  an  implied  limit  of  30847  bytes 
of  code  for  the  entire  program  and  32767 
bytes  of  either  global  or  local  data. 

Personal  Comments  on 
Writing  Augusta 

Ada  was  designed  for  the  U.S.  Depart¬ 
ment  of  Defense  as  the  result  of  studies 
conducted  by  the  DoD  during  the  mid  to 
late  seventies.  The  DoD  realized  that  its 
software  development  and  maintenance 
efforts  were  out  of  control.  With  pro¬ 
grams  written  in  numerous  languages  and 
dialects  and  then  made  to  run  on  several 
hardware  configurations,  the  DoD  was 
faced  with  a  nightmare. 

A  DoD-formed  study  group  recom¬ 
mended  that  the  DoD  sponsor  a  design 
for  a  single,  high-level  language  that  would 
fulfill  all  the  Department’s  data  process¬ 
ing  needs.  The  eventual  result  was  Ada, 
named  in  honor  of  Augusta  Ada  Byron, 


(a)  PROCEDURE  PI  IS 

I,J  :  INTEGER; 

PROCEDURE  P2  (X  :  INTEGER)  IS 
Y,Z:  STRING 
BEGIN 
NULL; 

END; 

BEGIN 

NULL; 

END; 

(b)  Contents  of  Symbol  Table  stack 

Z  •*-  Top  of  stack 

Y 

X 

P2 

J 

I 

PI  •*-  Bottom  of  stack 

Figure  1. 

The  symbol  table  uses  a  “stack”  to  keep  track  of  identifiers. 
The  most  recently  defined  symbols  always  appear  on  the 
top  of  the  stack,  (a)  shows  a  short  program,  (b)  shows  the 
symbol  table  when  the  compiler  has  reached  the  BEGIN  in 
procedure  P2. 
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the  Countess  of  Lovelace  and  the  daughter 
of  the  poet  Lord  Byron.  She  is  credited 
as  being  the  first  computer  programmer 
for  the  work  she  performed  on  Charles 
Babbage’s  mechanical  computing  engine 
during  the  mid  1800’s. 

The  language  that  was  produced  was 
strongly  influenced  by  a  number  of  exist¬ 
ing  languages,  including  Pascal,  Algol  and 
SIMULA.  While  Ada  contains  little  that  is 
particularly  novel,  it  does  collect  into  a 
single  language  a  number  of  state-of-the- 
art  concepts,  including  “packages”  for 
modular  compilation,  and  multi-tasking. 

Unfortunately,  to  satisfy  everyone’s 
needs,  the  language  that  was  created  be¬ 
came  quite  large.  Just  compare  the  size  of 
the  Ada  draft  standard  with  that  of  Pascal. 
The  table  of  contents  for  the  Ada  stan¬ 


dard  is  more  than  twice  as  large  as  that 
for  Pascal.  Further,  Ada’s  complexity 
forces  compilers  to  be  large,  complicated 
programs,  ill-suited  for  small  computers. 

The  DoD  registered  the  name  “Ada” 
as  a  trademark.  Only  compilers  that  im¬ 
plement  the  full  Ada  definition  may  be 
properly  called  “Ada.”  And  there  is  no 
Ada  subset  because  the  DoD  has  refused 
to  create  a  subset  definition.  (Most  of  the 
compilers  currently  advertised  as  “Ada” 
are,  in  fact,  Ada  subset  compilers.  They 
must,  however,  display  a  DoD-required 
notice  that  the  compiler  is  currently 
incomplete  but  that  it  will  be  developed 
into  full  Ada  and  submitted  to  the  gov¬ 
ernment  for  validation  at  a  later  date.) 

The  lack  of  a  well-defined  Ada  subset 
may  hinder  the  language’s  growth.  Full 


Ada  will  not  run  on  low-cost,  low-end 
systems,  such  as  TI-99s,  Commodore  64s, 
Ataris,  or  even  Apples.  And  even  develop¬ 
ment  on  large  personal  computer  systems 
will  be  difficult.  For  example,  IBM  Pascal 
requires  three  floppy  diskette  changes 
just  to  compile  and  link  a  single  program. 

Ada  is  fine  if  you  have  access  to  a 
minicomputer  or  a  “micro”  with  512 
Kbytes  of  memory  and  a  hard  disk.  Real¬ 
istically,  Pascal’s  big  push  to  popularity 
came  from  underneath,  particularly  with 
the  advent  of  the  UCSD  Pascal  system  for 
personal  computers.  An  Ada-subset  defi¬ 
nition  would  be  ideal  for  introductory 
computing  classes  which,  in  turn,  could 
provide  a  large  pool  of  programmers 
skilled  in  the  use  of  Ada. 


Designing  Augusta 

The  choice  of  features  in  Augusta 
was  influenced  by  the  type  of  software 
that  I  write.  That  includes  language  proc¬ 
essors,  text  editors,  operating  system  rou¬ 
tines,  and  an  occasional  game.  I  attempted 
to  produce  a  true  but  powerful  subset  of 
the  Ada  language  that  would  be  useful  for 
hobbyists  on  personal  computer  systems. 
Two  minor  extensions  were  made  to  Ada: 
the  use  of  the  “  @  ”  symbol  for  parameter 
passing,  and  UCSD  Pascal  style  strings. 

Once  the  compiler  is  rewritten  in 
Augusta,  these  extensions  will  be  removed 
and  additional  Ada  features  will  be  added, 
such  as  real  arithmetic,  “EXCEPTION” 
error  handling,  and  package  libraries  for 
modular  program  development. 

The  subset  that  was  chosen  provides 
a  language  sufficiently  powerful  to  be 
useful  in  a  wide  range  of  applications. 
Additional  Ada  constructions,  such  as 
packages,  would  be  nice  to  have  but  are- 
not  needed  for  a  boot -strap  compiler. 
Instead,  a  group  of  “built-in”  procedures 
and  functions  were  created  to  support 
Ada-like  terminal  and  file  system  access, 
string  handling,  and  other  functions. 
Once  Augusta  supports  packages,  these 
procedures  can  be  easily  moved  into 
package  definitions. 


Why  BASIC? 

BASIC  is  a  poor  language  for  produc¬ 
ing  large  programs.  But  there  were  several 
reasons  that  I  chose  —  or,  more  exactly, 
was  forced  to  choose  —  BASIC.  Since  I 
used  an  Osborne  I  for  all  program  devel¬ 
opment,  I  had  to  fit  everything  —  source, 
compiled  programs  plus  language  develop¬ 
ment  tools  -  on  two  92K  diskettes.  Pascal, 
my  language  of  choice,  simply  wouldn’t 
fit.  Other  languages,  like  Forth  or  C,  did 
not  appear  to  be  available  for  the  Osborne 
I  at  the  time  I  began  the  project. 

The  use  of  an  interactive  language, 
like  BASIC,  made  much  of  the  develop- 


(a) 

Identifier  Type  Kind  PInfo  Const  ObjSz  Addr  Lex 

■  8  n  n  n  ■  2  n  ■  2  :  1 


(b) 

Identifier  8 -byte  ASCII  string,  padded  with  spaces  if  necessary 

Type  The  “type”  of  the  identifier  (e.g.,  INTEGER,  STRING,  etc.) 
encoded  as  a  byte  value: 

0  =  string 

1  = integer 

2  =  character 

3  =  *  not  used  * 

4  =  boolean 

Kind  “Kind”  encoded  as  a  byte  value: 

0  =  constant 

1  =  array  variable 

2  =  procedure 

3  =  function 

4  =  type  definition 

5  =  scalar  variable 

PInfor  “Parameter  Information”  indicates  if  the  identifier  is  a  procedure 
or  function  parameter,  encoded  as  a  byte  value: 

0  =  Identifier  is  not  a  parameter 

1  =  IN  parameter 

2  =  OUT  parameter 
If  Kind  =  4  Then 

If  PInfo  =  0  Then  Identifier  is  array  type 
Else  Identifier  is  not  an  array 

Const  If  Kind  =  0  then  this  field  holds  the  value  of  a  constant;  otherwise, 
it  holds  the  size  of  an  array. 

ObjSz  “Object  Size”  is  the  size  in  bytes  of  an  element  of  the  structure 
(e.g.,  an  integer  has  an  ObjSz  of  2,  a  string  has  a  size  of  81,  and  an 
array  of  integers  also  has  a  size  of  2). 

Addr  The  address  as  an  offset  from  the  frame  mark  for  the  procedure  in 
which  the  identifier  is  used  (or  the  procedure  number  if  the  identi¬ 
fier  is  a  procedure  or  a  function). 

Lex  The  lexical  level  of  the  identifier. 

Figure  2. 

Detailed  layout  of  a  symbol  table  entry.  Each  entry  is  17  bytes  long  —  8  bytes 
to  store  the  actual  identifier  and  9  bytes  of  information  describing  the  identi¬ 
fier.  (a)  shows  the  entry  format  and  (b)  describes  the  fields  in  detail. 
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ment  easier  than  it  might  have  been. 
There  are,  however,  some  big  problems 
inherent  in  BASIC.  Having  only  line  num¬ 
bers  for  labels  and  nothing  but  global 
variables  made  work  very  hard  to  follow 
in  many  places.  Comments  had  to  be  kept 
to  a  minimum  as  they  take  up  memory 
space. 

In  addition,  Microsoft  BASIC  does 
not  have  multi-line,  user-defined  func¬ 
tions;  it  makes  poor  use  of  memory;  and 
it  has  a  poor  symbol  table  layout.  Each 
and  every  time  a  variable  name  is  used  in 
a  program,  BASIC  stores  the  complete 
variable  name  (in  ASCII),  even  though 
BASIC  “tokenizes”  much  of  the  language. 
Consequently,  variable  names  had  to  be 
kept  short,  which  only  compounded  the 
problem  of  too  few  comments.  On  the 
bright  side,  BASIC-80  is  fairly  fast  as  far 
as  interpreters  go,  and  the  BASIC-80 
compiler  does  an  excellent  job  of  produc¬ 
ing  compiled  code. 

Compiler  Availability 

The  compiled  version  of  Augusta, 
which  is  32K  in  length,  compiles  programs 
at  well  over  300  lines  per  minute  (timed 
on  an  Osborne  I  -  much  faster  compile 
speeds  have  been  seen  on  systems  using 
decent  disk  drives).  Since  there  is  no  link 
step,  compiled  programs  may  be  executed 
immediately. 

The  p-code  interpreter  requires  just 
over  7K  of  memory  and  executes  pro¬ 
grams  at  a  speed  comparable  to  other 
p-code  languages  (see  Table  2,  page  34, 
DDJ  No.  77,  March  1983).  In  addition, 
Augusta  p-code  programs  average  about 
30%  fewer  bytes  of  generated  code  than 
other  p-code  systems. 

The  Augusta  compiler,  including 
source,  CP/M  (Z80-based)  p-code  inter¬ 
preter,  a  powerful  debug  utility,  and  a  com¬ 
prehensive  160-page  reference  guide  is 
available  from  Laboratory  Microsystems, 
Inc.,  4147  Beethoven  Street,  Los  Angeles, 
California  90066 ;  (2 13)  306-7412. 
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Table  I. 

Cross  Reference  of  Major  Subroutines 


Line  Title  And/Or  Function 


1000  Outer  block  of  compiler  (prompts  for  source  and  code 
files,  and  closes  and  updates  the  code  file  at  exit) 

1110  Initialization 

1230  Open  a  new  source  file 

1250  Convert  CH$  to  upper-case  character 

1280  GETLINE  (read  a  source  line  from  the  input  file) 

1360  GETCH  (setsCHS  to  a  character  from  the  input) 

1400  GETSYM  (the  lexical  analyzer) 

1780  Additional  initialization,  including  reading  the 
keywords  data  file 

1890  Look  up  keyword  in  hash  table  KEY$() 

1970  COMPILATION  (from  syntax  diagrams) 

2010  PARSE  PROC  (parses  a  procedure  definition) 

2100  PROCFORMALPART  (parses  procedure  parameter 
list) 

2160  PROCPARAMDECL  (parses  individual  parameter 
declaration  within  the  parameter  list) 

2250  SUBTYPEINDICATIONUNIT  (assigns  a  “type”  to  a 
variable  list) 

2300  OBJSZ  (determines  the  size  in  bytes  of  a  variable  or 
object  —  e.g.,  an  array) 

2340  PARSEFUNC  (parses  a  function  definition) 

2440  BODYPART  (see  syntax  diagrams  in  DDJ  No.  75) 
2480  DECLPART 
2560  OBJDECL 

2650  CONSTANT  (constant  declarations) 

2700  ARRAY  (array  declarations) 

2770  PRAGMA  (initial  parsing  of  pragmas) 

2790  STMT  (see  STMT  PART  in  syntax  diagrams) 

2810  SEQOFSTMTS  (see  SEQ  OF  STMTS  in  syntax 
diagrams) 

2830  NULL  statement 

2850  BLOCK  (optional  DECLARE  followed  by 
BEGIN-END) 

2890  EXIT  statement 
2930  RETURN  statement 
2970  IF  statement 
3100  EXPR  (expression  parsing) 

3190  RELATION  (relational  subexpressions) 

3290  SE  (simple  expression  parsing  including  addition, 
subtraction) 

3350  TERM  (multiplication  operators) 

3420  SKIP  ; 

3440  ID  (procedure  calls  or  assignment  statements) 

3570  ACTUALPARAM  (parameters  being  passed  to  a 
procedure  or  function) 

3610  PRIMARY  (expression  parsing) 

3635  Generate  “load  constant”  instructions 
3650  Generate  “  LCA”  load  string  instruction 
3710  Generate  an  array  reference  for  integers,  chars, 
booleans 


20 


Line  Title  And/Or  Function 

3745  Parenthesized  expression 
3800  Generate  a  string  array  reference 
3820  Generate  “Load  Value”  instructions,  including 
LDO,  LDL,  and  LDU 
3831  Global  loads 
3834  Local  loads 

3850  ADD  ID  (add  identifier  to  symbol  table) 

3890  Look  up  IDS  in  the  symbol  table 

3990  Write  a  byte  of  code  to  the  code  file 

4010  Read  a  word  of  code  from  the  code  file 

4030  Write  a  word  of  code  to  the  code  file 

4060  Generate  load  address  instructions 

4085  Global  load  addresses 

4090  Local  load  addresses 

4100  Generate  call  procedure  opcodes 

4140  GETBUF  (locate  a  buffer  to  the  code  file) 

4260  Read  a  byte  from  the  code  file 

4280  Push  X  onto  compiler’s  stack 

4300  Pop  top  of  compiler’s  stack  into  X 

4320  Parse  LOOP  statements 

4380  FOR  loop 

4580  WHILE  loop 

4590  Basic  LOOP-END  LOOP 

4630  CASE  statement 

4810  OTHERS  clause  of  CASE 

4830  PRAGMA  (additional  processing  for  pragmas) 

49 1 0  WRITEPROC  (creates  an  entry  in  the  procedure  table) 
4930  Does  type  checking  for  booleans 
4960  Does  type  checking  for  integers 
4990  Keeps  track  of  the  maximum  offset,  or  variable 
address 

5020  Error  handling 


End  Table  I. 
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Table  II. 

Variable 

Variable  Dictionary 

Name 

Use 

The  dictionary  includes  those  variables  that  are  not  used 

R2 

Current  offset  within  the  code  file  buffer 

as  “constant”  symbols.  All  symbols  are  integers  unless  ex- 

s$() 

Holds  the  symbol  table  as  a  stack  of  strings 

plicitly  labelled  as  “real”  using  “  !”  or  string  using 

50 

51 

Internal  stack  space 

Source  Input  file  number 

Variable 

SP 

Internal  Stack  Pointer 

Name 

Use 

S$ 

“string”  returned  by  GETSYM 

ADDR 

“Address”  field  of  a  symbol  table  entry 

SSP 

Symbol  table  Stack  Pointer;  points  to  top  of  S $ ( ) 

B() 

Keeps  track  of  which  code  file  record  matches 

stack 

which  buffer 

T 

Holds  the  Token  “constant”  returned  by  GETSYM 

BS() 

Holds  the  code  file  output  buffers 

TO 

Value  of  the  token  that  is  expected  by  the  parser 

B 

Buffer  pointer;  points  to  next  character  in  BUF$ 
to  read 

TN 

Token  Number  (holds  the  numeric  equivalent  of 
a  constant  read  by  GETSYM) 

BUF$ 

Holds  current  source  line  from  input  file 

TSP 

Internal  “Type”  Stack  Pointer;  used  to  parse 

CASES 

Counts  the  number  of  cases  in  a  case  statement 

expressions 

CLST 

Non-zero  if  listing  on  the  CRT 

TT$ 

Equal  to  CHR$(T) 

CONST 

The  “constant”  field  in  a  symbol  table  entry 

TY  () 

Expression  “type”  checking  stack 

CPROC 

Contains  the  number  of  the  procedure  being 

TYPE 

“Type”  field  of  a  symbol  table  entry 

compiled 

V 

Used  to  convert  a  word  to  two  bytes 

cs 

Name  of  the  code  file 

VLOC1  Address  of  byte  1  of  variable  V  in  memory; 

CHS 

Holds  the  current  input  character  from  the 

V  is  then  accessed  with  PEEKQ 

source  file 

VLOC2  Address  of  byte  2  of  variable  V 

CB 

Code  Base  points  to  first  byte  of  code  for  a 

w 

Holds  the  Word  value  to  write  out 

procedure; CP  is  an  offset  from  CB 

X 

The  value  pushed  or  popped  onto  the  stack 

CP 

Code  Pointer;  points  to  next  byte  of  code  in 
code  file 

X! 

Real  variable  used  in  searching  symbol  table  for 
integers  >  32767 

DS 

Dummy  string  variable 

XITJP 

Points  to  the  head  of  a  linked  list  of  UJP  instruc- 

E 

GC 

HASH 

Set  to  the  Error  code  value 

Global  Code  counter;  counts  the  number  of 
bytes  of  code 

Used  in  looking  up  a  keyword  identifier 

tions  (used  to  EXIT  a  loop) 

End  Table  II. 

IDS 

KEYSO 

KIND 

Holds  an  identifier  name 

An  array  holding  all  of  the  keyword  identifiers 

The  “kind”  field  of  a  symbol  table  entry 

LEX 

The  lexical  level  field  of  a  symbol  table  entry 

Table  III. 

LL 

LOCI 

The  Lexical  Level  of  the  procedure  being  compiled 
Used  in  searching  the  symbol  table 

Summary  of  Error  Codes 

LOC2 

Used  in  searching  the  symbol  table 

Code 

Meaning 

LFJP 

Points  to  the  head  of  a  linked  list  of  FJP  instruc- 

1 

Unrecognized  character  in  source  input 

tions  (used  for  backpatching) 

LPFLG 

Set  to  -1  if  inside  a  LOOP-END  LOOP,  otherwise 

2 

Undefined  identifier 

0.  EXIT  is  only  allowed  if  LPFLG  is  non-zero 

3 

Syntax  error  in  declaration  part 

LUJP 

Points  to  the  head  of  a  linked -list  of  UJP  instruc- 

4 

Syntax  error 

tions  (used  for  backpatching) 

5 

CASE  selector  must  be  integer  or  character  constant 

MAP() 

Hash  “function”  array 

6 

Invalid  pragma 

MO 

Highest  or  maximally  used  record  in  the  code  file 

7 

Undefined  attribute 

MB 

Maximum  number  of  code  file  Buffers 

8 

Undefined  type 

MXOF 

The  highest  variable  offset  used  during  the 

9 

Type  mismatch 

current  procedure  definition 

10 

String  constant  exceeds  source  line 

OBJSZ 

“Object  Size”  field  of  a  symbol  table  entry 

11 

Invalid  character  constant 

OFST 

The  current  variable  offset  used  during  the 

12 

Unexpected  end  of  input  file 

current  procedure  definition 

13 

Semicolon  missing  —  assumed  present 

OLDB 

P1NFO 

Marks  the  start  of  a  token;  used  in  GETSYM 
“Parameter  Info”  field  of  a  symbol  table  entry 

14 

EXIT  is  only  allowed  inside  of  LOOP-END  LOOP 

PLST 

Non-zero  if  listing  to  the  printer 

End  Table  III. 

PROC 

RO 

Counts  the  number  of  procedures  in  a  program 

Set  to  the  current  code  file  buffer 

R 1 

Code  file  record  to  write  next  byte  of  code 

(Table  IV  begins  on  page  22) 
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Table  IV. 

Code 

Token  expected 

Code 

Token  expected 

“EXPECTED”  Error  Message  codes, 

in  the  form. 

16 

identifier 

38 

FUNCTION 

nn  EXPECTED 

17 

string  constant 

39 

IF 

where  nn  is  defined  below. 

18 

,  (comma) 

40 

IN 

19 

;  (semicolon) 

41 

IS 

Code 

Token  expected 

20 

:  (colon) 

42 

LOOP 

21 

=> 

43 

LAST 

O 

’  (single  quote) 

22 

:= 

44 

LENGTH 

1 

*  not  used  * 

23 

.  (period) 

45 

MOD 

2 

integer  constant 

24 

. .  (double  period) 

46 

NOT 

3 

(  (left  parenthesis) 

25 

character  constant  as  ’x’ 

47 

NULL 

4 

)  (right  parenthesis) 

26 

@  symbol 

48 

OF 

5 

* 

27 

AND 

49 

OR 

6 

/ 

28 

ARRAY 

50 

OTHERS 

7 

+ 

29 

BEGIN 

51 

OUT 

8 

- 

30 

CASE 

52 

PRAGMA 

9 

< 

31 

CONST 

53 

PROCEDURE 

10 

<= 

32 

DECLARE 

54 

RETURN 

1  1 

> 

33 

ELSE 

55 

REVERSE 

12 

>  = 

34 

ELSEIF 

56 

THEN 

13 

= 

35 

END 

57 

WHEN 

14 

/= 

36 

EXIT 

58 

WHILE 

15 

37 

FOR 

End  Table  IV. 

Augusta  Part  IV 

Listing  One 

(Text  begins  on  page  12) 

This  is  Part  2  of  the  Augusta  Compiler 
listing,  continued  from  the  May,  1983 
issue  ( DDJ  No.  79,  Augusta  Part  III, 
Listing  Two,  pages  20-26).  This  in¬ 
stallment  concludes  the  listing  of  the 
compiler. 

Augusta  Compiler,  Copyright  ©  1983 
by  Computer  Linguistics.  Permission 
is  granted  to  individuals  to  use  the 
compiler  for  their  personal  use.  Un¬ 
authorized  distribution  is  expressly 
prohibited.  Augusta  is  a  trademark 
of  Computer  Linguistics. 

3174  IF  (TY(TSP)OTBOL)  OR 

tTY (TSP) <  >TY tTSP-1 ) )  THEN  E=9: 

GOTO  5020 

3175  TSPUSP-1: 

GOSUB  4300: 

LFJP=X : 

GOSUB  4300: 

PREV=X : 

IF  UKANDOCTHEN  THEN  M=PAND  ELSE  N=P0R 
3178  GOSUB  3990: 

GOTO  3120 
3180  T2=CPs 

WHILE  LFJPOOi 
CP=LFJP: 

GOSUB  4010: 

LFJP=W: 

W=T2-CP-2: 

GOSUB  4030: 


NEND: 

CP=T2: 

RETURN 

3190  ’RELATION 
3200  GOSUB  3300 

3210  IF  INSTR (REL0PS*, TT«)=0  THEN  RETURN 
3220  «=T: 

GOSUB  4280: 

60SUB  1400 
3230  60SUB  3290: 

IF  TYITSPIOTINT  AND  TY(TSP)OTCHR  AND 
TV  <TSP)  OTBOL  GOTO  3240 
3235  IF  TYtTSP) < >TY CTSP-1 )  THEN  E=9: 

60T0  5020  ELSE  TSP=TSP-1: 

TY (TSP)=TB0L 
3240  GOSUB  4300: 

IF  X=LES  THEN  W=PLESI  ELSE  IF  X=LEQ 
THEN  W=PLEQI  ELSE  IF  X=6T  THEN  H=PSTRI 
3245  IF  X=6EQ  THEN  W=P6EQI  ELSE  IF  X=EQ 

THEN  W=PEQUI  ELSE  IF  X=NEB  THEN  W=PNEQI 
3250  GOSUB  3990: 

60T0  3210 

3240  IF  TYITSPIOTSTR  OR 

TYlTSPIOTY(TSP-l)  THEN  E=9: 

60T0  5020  ELSE  TSP=TSP-1: 

TY!TSP)=TB0L 
3270  GOSUB  4300: 

IF  X=LES  THEN  N=PLESSTR  ELSE  IF  X=LEB 
THEN  W=PLEQSTR  ELSE  IF  X=6T  THEN 
W=P6TRSTR 

3275  IF  X-6EQ  THEN  W=PGEQSTR  ELSE  IF 

X=EB  THEN  W=PEBUSTR  ELSE  IF  X=NE8  THEN 
W=PNEBSTR 
3280  GOSUB  3990: 

GOTO  3210 


3290  'SE 

3300  IF  INSTR(UNARY0PS*,TT*)  THEN  X=T: 


GOSUB  42B0: 

X-l: 

GOSUB  42B0: 

GOSUB  1400  ELSE  X=0s 
GOSUB  4280 
3310  GOSUB  3350: 

GOSUB  4300: 

IF  X=1  THEN  GOSUB  4300: 

IF  X=SUBT  THEN  W=PKGIs 
GOSUB  3990  ELSE  W=PN0T: 

GOSUB  3990 

3320  IF  INSTR ( ADD0PS* , TT*) =0  THEN  RETURN 
3330  X=T: 

GOSUB  4280: 

60SUB  1400: 

GOSUB  3350: 

GOSUB  4300: 

IF  X=ADD  THEN  W=PADI  ELSE  W=PSBI 
3340  IF  TYITSPIOTINT  THEN  E=9: 

GOTO  5020  ELSE  TSP=TSP-1: 

GOSUB  3990: 

GOTO  3320 


3350  ’TERN 
3340  60SUB  3410 

3370  IF  INSTR (NULOPS* , TT* ) =0  THEN  RETURN 
3380  X=T: 

GOSUB  4280: 

GOSUB  1400: 

GOSUB  3410 

3390  IF  (TY(TSP)OTY(TSP-ll)  OR 
(TY(TSP)OTINT)  THEN  E=9: 

60T0  5020  ELSE  TSP=TSP-1 
3400  GOSUB  4300: 

IF  X=HUL  THEN  W=PHPI  ELSE  IF  X=DIV  THEN 
W=PDV I  ELSE  W=PH0D I 

(Continued  on  page  24) 
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3410  SOSUB  3990: 
B0T0  3370 


3420  ’SKIP  ; 

3430  IF  T=SEMIC0L0N  THEN  60SUB  1400: 
RETURN  ELSE  E=13: 

60SUB  5110: 

RETURN 


3440  ’ID 
3450  60SUB  3690: 

IF  KIND02  THEN  X=TYPE: 
G0SUB  4260: 

G0SUB  3490: 

GOTO  3530  ELSE  X=ADDR: 
GDSUB  4280: 

X=LEX : 

GDSUB  4280 


3460  G0SUB  1400: 

IF  T=SEMIC0L0N  GOTO  3480  ELSE  T0=LP: 
G0SUB  1960 
3470  GOSUB  3570: 

T0=RP: 

G0SUB  1960 
3480  G0SUB  4100: 

60SUB  3420: 

RETURN 

3490  G0SUB  4060: 

G0SUB  1400 

3500  IF  KINDOI  THEN  RETURN  ELSE  X=OBJSZ: 

G0SUB  4280 
3510  T0=LP: 

60SUB  1960: 

G0SUB  3100: 

60SUB  4960: 

G0SUB  4300: 

IF  X=2  THEN  N=PIND  ELSE  N=PIXA: 

60SUB  3990: 

N=X 

3520  GQSUB  3990: 

T0=RP: 

60SUB  1960: 

RETURN 

3530  T0=C0L0NEQ: 

SOSUB  1960 
3540  SOSUB  3100: 

GOSUB  4300: 

IF  NOT 4 X=TV (TSP)  OR  (X=TINT  AND 
TY 4TSP1 =TB0L)  OR  <X=TBOL  AND 
TY (TSP ) =T  I  NT) I  THEN  E=9: 

GOTO  5020 

3550  IF  X=TSTR  THEN  N=PSAS  ELSE  H=PSTO 
3560  TSP=TSP-I: 

GOSUB  3990: 

GOSUB  3420: 

RETURN 


|  3570  ’ ACTUALPARAN 
3580  IF  T=AT  THEN  GOSUB  1400: 
TO=IO: 

SOSUB  1950: 

GOSUB  3890: 

GOSUB  3490  ELSE  GOSUB  3100: 
TSP=TSP-I 

j  3590  IF  T=C0HNA  THEN  GQSUB  1400: 

GOTO  3580 
I  3600  RETURN 


3610  ’ PRIMARY 

3620  IF  MP  THEN  GOSUB  1400: 
GOSUB  3100: 

T0=RP: 

GOSUB  1960: 

RETURN 


3630  IF  T=C  THEN  TSP=TSP*1: 
TY (TSP) =TINT : 

GOSUB  3640: 

60SUB  1400: 

RETURN 

3633  IF  T=CH  THEN  TSP=TSP+1: 
TY (TSP) =TCHR: 

GOSUB  3640: 

GOSUB  1400: 

RETURN  ELSE  6OT0  3650 


3635  ’LD  CONS 

3640  IF  TN=-1  THEN  N=PSL0CN1: 

60T0  3645  ELSE  IF  TN>-1  AND  TN<16  THEN 
N=64+TN: 

GOTO  3645 

3643  IF  TN>0  AND  TN<256  THEN  N=PSLDC: 

GOSUB  3990: 

N=TN: 

GOSUB  3990: 

RETURN  ELSE  «=PLDCI: 

GOSUB  3990: 

N=TN: 

GOSUB  4030: 

RETURN 

3645  GOSUB  3990: 

RETURN 

3650  IF  rose  GOTO  3670  ELSE  TSP=TSP+1: 

TY (TSP) =TSTR 
3660  N=PLCA: 

60SUB  3990: 

N=LEN(SI): 

GOSUB  3990: 

FOR  1=1  TO  LEN(SI) : 

N=ASC(HID*(S*,III: 

60SUB  3990: 

NEXT  I: 

GOSUB  1400: 

RETURN 
3670  T0=ID: 

GOSUB  1950 
3680  GOSUB  3890: 

IF  KIND=0  THEN  TSP=TSP*1: 

TY (TSP) =TYPE: 

TN=C0NST: 

GOSUB  3640: 

60SUB  1400: 

RETURN 


3682  GOSUB  1400: 

IF  T=S0U0TE  GOTO  3780 
|  3685  IF  KIND=4  THEN  X=TYPE: 
GOSUB  4280; 

TO=LP: 

60SUB  1960: 

GOSUB  3100: 

TO=RP: 

GOSUB  1960: 

GOSUB  4300: 

TY  (TSP) =X: 

RETURN 


3690  TSP=TSP+1: 

TY (TSP) =TYPE: 

IF  TYPE=0  GOTO  3800 

3700  IF  KINDOI  GOTO  3740  ELSE  GOSUB  4060 
3710  TO=LP: 

GOSUB  1960 
3720  GOSUB  3100: 

IF  TYITSPIOTINT  THEN  E=9; 

GOTO  5020  ELSE  TSP=TSP-1: 

N=P1ND: 

GOSUB  3990: 

N=PSIND0: 

GOSUB  3990 
3730  T0=RP: 

GOSUB  1960: 

RETURN 

3740  IF  KIND03  THEN  GOSUB  3760: 

RETURN  ELSE  X=ADDR; 

GOSUB  4280: 

X=LEX: 

GOSUB  4280 

3745  IF  T=LP  THEN  GOSUB  1400: 

GOSUB  3570: 

TO=RP: 

GOSUB  1960 
3750  GOSUB  4100: 

RETURN 

3760  GOSUB  3820: 

IF  PINF0=2  THEN  N=PSINDO: 

GOSUB  3990 
3770  RETURN 
3780  TSP=TSP+1: 

TY ( TSP) =T INT: 

GOSUB  1400: 

IF  T=KLAST  THEN  N=PLDCI: 

GOSUB  3990: 

N=CQNST : 

GOSUB  4030: 

GOTO  3790 

3785  IF  T=KLEN  THEN  GOSUB  4060: 

N=PLDB: 

GOSUB  3990  ELSE  E=7: 

60T0  5020 
3790  GOSUB  1400: 

RETURN 

3800  IF  KINDOI  60T0  3810  ELSE  GOSUB  4060: 
X=0BJS2: 

GOSUB  4280: 

TO=LP: 

GOSUB  1960: 

60SUB  3100 

3805  IF  TYITSPIOTINT  THEN  E=9: 

60T0  5020  ELSE  TSP=TSP-1: 

60SUB  4300: 

H=PIXA: 

GOSUB  3990: 

N=X: 

GOSUB  3990: 
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TO=RP : 

GOSUB  1940: 
RETURN 

3810  GOSUB  4040: 
RETURN 


3820  'LD  VAL 

3830  IF  LEX=1  SOTO  3831  ELSE  IF  LEX=LL 
GOTO  3834  ELSE  W=PLOD: 

GOSUB  3990: 

H=LL-LEX : 

GOTO  3845 


3831  'GLOBAL 

3832  IF  ADDR<254  THEN  N=PSLDO: 

GOTO  3840  ELSE  H=PLDO: 

GOTO  3845 

3834  'LDL 

3835  IF  ADDR>=0  AND  ADDRO  THEN  M=PSLDLO+ADDR: 

GOSUB  3990: 

RETURN 

3834  IF  ADDR>0  AND  ADDR<8  THEN  N=PSLDL: 

60T0  3840  ELSE  N=PLDL: 

GOTO  3845 


3840  ’ B, B 
3842  GOSUB  3990: 
N=ADDR: 
GOSUB  3990: 
RETURN 


3845  ’ B, H 
3847  60SUB  3990: 
N-ADDR: 
60SUB  4030; 
RETURN 


3850  'ADD  ID 

3840  IF  LEN(SI(SSP))+17>255  THEN  SSP=SSP+1 
3870  St (SSP) =XD*+CHR*  (TYPE)  +CHR$ (KINDI ♦ 

CHR* (PINFO) +MKI* (CONST) +CHR* (OBJSZ)  + 
HKI $ ( ADDR ) *CHR$ (LL ) *St I SSP I 
3880  RETURN 


3890  'LOOKUP  ID 
3900  L0C1=SSP 

3910  L0C2=INSTR(S« (LOCH , ID*) : 

IF  L0C2  GOTO  3920  ELSE  L0CI=L0CI-1: 
IF  LOCI  GOTO  3910  ELSE  E=2: 

60T0  5020 

3920  T9=VARPTR<S*<L0C1 ) ) : 

POKE  VLOC , PEEK ( T9+1 ) : 

POKE  VLOC 1, PEEK (T9*2): 

T9=V+L0C2-1 
3930  TYPE=PEEK ( T9+8) : 

KIND=PEEK(T9+91: 

PINFO=PEEK (T9+10) ! 

POKE  VL0C,PEEK(T9*11): 

POKE  VL0C1 , PEEK  <  T9+12 1 : 

CONST=V 

3940  OBJ S2=PEEK ( T9+13) : 


LEX=PEEK (T9+14) : 

POKE  VLOC, PEEK ( T9+1 4) : 
POKE  VL0C1 , PEEK (T9+15) : 
ADDR=V: 

RETURN 


3990  ’ 6ENBYTE 
4000  GOSUB  4140: 

FIELD  II, R2  AS  Dt,l  AS  Dt: 
LSET  D*=CHR»(N): 

CP=CP*1: 

RETURN 


4010  ' READNRD 
4020  T1=CP: 

GOSUB  4240: 
POKE  VLOC, H: 
CP=CP+1: 

60SUB  4240: 
POKE  VL0C1 , H: 
N=V: 

CP=T1: 

RETURN 


4030  'GEKHORD  N 
4040  GOSUB  4140: 

IF  R2< 127  THEN  FIELD  II,  R2  AS  D*,2  AS  D»: 
LSET  Dt=F1KI*(M) : 

CP=CP+2: 

RETURN 
4050  V=N: 

N=PEEK(VLOC)i 
GOSUB  3990: 

M=PEEK ( VLOC 1 ) : 

GOSUB  3990: 

RETURN 
4040  'LD  ADR 

4070  IF  PINF0=2  THEN  GOSUB  3820: 

RETURN 

4080  IF  LEX=!  GOTO  4085  ELSE  IF  LEX=LL 
GOTO  4090  ELSE  N=PLDA: 

GOSUB  3990: 

H=LL-LEX: 

60T0  3845 


4085  '6L  ADR 

4087  IF  ADDR<254  THEN  N=PSLAO: 
60T0  3840  ELSE  H=PLAO: 
GOTO  3845 


4090  ’LDL  ADR 

4095  IF  ADDR>=0  AND  ADDR<254  THEN  1PPSLLA: 
60T0  3840  ELSE  ti=PLLA: 

GOTO  3845 


4100  'CALL  PROC 
4110  GOSUB  4300: 
LEX=X : 
6DSUB  4300: 
ADDR=X 


4120  IF  LEX=0  THEN  N=PCSP  ELSE  IF  LEX=2 
THEN  N-PCSP  ELSE  IF  LEX=LL+1  THEN 
M=PCLP  ELSE  «=PCIP 
4130  GOSUB  3990: 

N=ADDR: 

GOSUB  3990: 

RETURN 


4140  ’ 6ETBUF 
4150  T9=CP+CB: 

R1=T9\ 128+ 1 : 

R2=T9  AND  127: 

IF  R1=R0  THEN  RETURN 
4140  FIELD  11,128  AS  Dt: 

J=1 

4170  IF  B(J)=R0  OR  B < J I =0  60T0  4190  ELSE  J=J+ls 
IF  J<=«B  GOTO  4170 
4180  LSET  B$(0)=Dt: 

J-INT (RND1NB)*1: 

LSET  Dt=Bt(J)s 
PUT  1 1 , B ( J ) : 

LSET  Bi (J ) =B$ (0) : 

B ( J ) =R0: 

60T0  4200 

4190  LSET  Bi ( J ) =Dt : 

B ( J I =R0 
4200  J=1 

4210  IF  B(J)-R1  GOTO  4240  ELSE  J=J+li 
IF  J<=NB  GOTO  4210 
4220  GET  II,  Rl: 

R0=R1: 

IF  R1>N0  THEN  N0=R1 
4230  RETURN 
4240  LSET  D«=B*!J): 

R0=R1 : 

IF  RDNO  THEN  H0=R1 
4250  RETURN 


4240  ’READBYTE 
4270  GOSUB  4140: 

FIELDil ,R2  AS  D(,l  AS  Dt: 
H-ASC(Dt) : 

RETURN 


4280  ’PUSH 
4290  S ( SP ) =  X : 
SP=SP+1 
RETURN 


4300  ’POP 
4310  SP=SP-1: 

X=S (SP) : 
RETURN 


4320  ’LOOP 

4330  IF  TOKNHILE  GOTO  4370 
4340  GOSUB  1400: 

X=CP: 

GOSUB  4280: 

GOSUB  3100: 

GOSUB  4930 

4350  tbPFJP:  (Continued  on  page  28) 
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60SUB  3990: 

X=CP: 

60SUB  4280: 

N=0: 

60SUB  4030: 

GOSUB  4590: 

GOSUB  4300 
4340  T 1=CP: 

CP=X: 

H=T1-X+1: 

60SUB  4030: 

CP=Tl: 

t*=PUJP: 

GOSUB  3990: 

SOSUB  4300: 

N=T-Cr-2: 

60SUB  4030: 

GOSUB  4420: 

RETURN 

4370  IF  TOKFOR  GOTO  4580 
4380  GOSUB  1400: 

T0=ID: 

60SUB  1950: 

X=0FST : 

60SUB  4280: 

GOSUB  5400 
4390  ADDR=0FST: 

TYPE=1: 

KIND=5: 

PINFQ=0: 

GOSUB  3850 
4400  GOSUB  1400: 

T0=KIN: 

GOSUB  1940 

4410  IF  T=KREVERSE  THEN  *=-l: 

GOSUB  1400  ELSE  X=1 
4420  GOSUB  4280: 

N=PLLA: 

GOSUB  3990: 

N=0FST: 

GOSUB  4030 
4430  GOSUB  3290: 

GOSUB  4940: 

N=PST0: 

GOSUB  3990 
4440  T=CPs 

GOSUB  4280: 

N=PLDL: 

GOSUB  3990: 

W=OFST: 

GOSUB  4030 
4450  T0=D0TD0T: 

60SUB  1940: 

60SUB  3290: 

GOSUB  4940 

4440  GOSUB  4300: 

T1=X: 

GOSUB  4300: 

IF  X<0  THEN  K=P6E0I  ELSE  W=PLEBI 


4470  GOSUB  3990: 

W=PFJP: 

GOSUB  3990: 

60SUB  4280: 

Ml: 

GOSUB  4280 
4480  X=CP: 

GOSUB  4280: 

«=0: 

60SUB  4030: 

X=0FST: 

60SUB  4280: 

0FST=0FST+2: 

60SUB  4990 

4490  60SUB  4590: 

GOSUB  4300: 

T3=X: 

60SUB  4300: 

T1=X: 

GOSUB  4300: 

T2=X: 

60SUB  4300: 

IF  X<0  THEN  N=PDECL  ELSE  M=PINCL 
4500  GOSUB  3990: 

N=T3: 

GOSUB  4030 
4520  N=PUJP: 

60SUB  3990 
4530  N=T2-CP-2; 

GOSUB  4030: 

T2=CP: 

CP=T1 : 

M2-T1-2: 

60SUB  4030: 

CP=T2 

4550  GOSUB  5500: 

GOSUB  5700 
4540  GOSUB  4300: 

0FST=X 

4570  GOSUB  4620: 

RETURN 
4580  X=CPs 

60SUB  4280: 

GOSUB  4590: 

N=PUJP: 

60SUB  3990: 

GOSUB  4300: 

«=X-CP-2: 

GOSUB  4030: 

GOSUB  4620: 

RETURN 
4590  T0=KL00P: 

GOSUB  1960: 

X=XITJP: 

60SUB  4280: 

T1TJP=0: 

X=LPFLG: 

GOSUB  4280: 

LPFL6=-1: 

60SUB  2810 
4600  T0=KEND: 

GOSUB  1960 
4610  TO=KLOOP: 

60SUB  1960: 

60SUB  4300: 

T5=X: 

GOSUB  4300: 

T6=X: 

GOSUB  3420: 

RETURN 


4620  T2=CP: 

NHILE  XIUPOO: 
CP=XITJP: 

GOSUB  4010: 

XITJP=N: 

N=T2-CP-2: 

GOSUB  4030: 
WEND: 

CP=T2: 

LPFL6=T5: 

XITJP=T6: 

RETURN 


4630  'CASE 
4640  GOSUB  1400: 

60SUB  3100: 

IF  TY ( TSP) < >TI NT  AND  TYITSPIOTCHR  THEN 
E=9: 

GOTO  5020 
4645  TSP=TSP-1 : 

U=PX JPs 
60SUB  3990: 

X=CP; 

GOSUB  4280: 

60SUB  4030: 

GOSUB  4030: 

GOSUB  4030: 

CASES=0: 

LUJP=0: 

T0=KIS: 

GOSUB  1960 
4650  T0=KNHEN: 

60SUB  1960: 

IF  TOOTHERS  GOTO  4810  ELSE  T1=0 
4660  IF  T=ID  THEN  60SUB  3890: 

TN=C0NST: 

IF  TYPE=1  OR  TYPE=2  THEN  T=C 
4670  IF  TOCH  AND  TOC  THEN  E=5: 

GOTO  5020  ELSE  MN: 

60SUB  4280: 

Tl*Tl*li 
GOSUB  1400: 

IF  T=BAR  THEN  GOSUB  1400: 

60T0  4660 
4680  60SUB  4780 

4690  IF  T=KNHEN  GOTO  4650  ELSE  1=0: 

GOSUB  4280: 

GOSUB  4280: 

1*1: 

GOSUB  4280: 

CASES=CASES+1 
4700  T0=KEND: 

GOSUB  I960: 

T0=KCASE: 

GOSUB  1960 
4710  Tl=SP-4: 

T3=32767: 

T4=-32767  s 

FOR  1=1  TO  CASES- 1: 

T2=S(T1) : 

Tl=Tl-2: 

FOR  J=1  TO  T2: 

IF  S(T1I<T3  THEN  T3=S(T1) 

4715  IF  S(Tt) >T4  THEN  T4=S(T1I 
4720  T1=T1-1: 

NETT  J: 

NETT  I: 

N=PUJP: 

SOSUB  3990: 
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T5=CP : 

SOSUB  4300: 
60SUB  4300: 
T1 =X : 

GOSUB  4300 


4725  IF  X=-l  THEM  H=Tl-CP-2: 
60SUB  4030  ELSE  «=LUJP: 
LUJP=CP: 

GOSUB  4030 
4730  FOR  J=T3  TO  T4: 

H=T5-CP-3: 

GOSUB  4030: 

NETT  I 'BUILD  TABLE 
4740  T7=CP: 

FOR  1=1  TO  CASES-1: 
60SUB  4300: 

T2=T: 

60SUB  4300; 

T6=X : 

FOR  T8=I  TO  T2: 

GOSUB  4300 

4745  CP=T5*<X-T3) *2+2: 
N=T6-CP-2: 

GOSUB  4030: 

NETT  TB: 

NETT  I; 

CP=T7 

4750  GOSUB  4300: 

T2=CP: 

CP=T: 

M=T3: 

GOSUB  4030: 

M=T4: 

GOSUB  4030: 

M=T5-CP-2: 

GOSUB  4030 
4740  WHILE  LUJPOO; 

CP=LUJP: 

GOSUB  4010: 

LUJP=N: 

M=T2-CP-2: 

GOSUB  4030: 

MEND: 

CP=T2 

4770  GOSUB  3420: 

RETURN 
4780  T0=E8GT: 

GOSUB  1940: 

3=CP: 

60SUB  4280: 

T=T1: 

GOSUB  4280: 

T=LUJP: 

60SUB  4280: 
CASES=CASES*1: 

X=CASES: 

GOSUB  4280: 

GOSUB  2810 
4790  M=PUJP: 

GOSUB  3990: 

60SUB  4300: 

CASES=T: 

GOSUB  4300: 

LUJP=T 
4 BOO  N=LUJP: 

LU3P=CP: 

GOSUB  4030: 

RETURN 


4810  'OTHERS 
4820  GOSUB  1400: 
T=-l: 

GOSUB  4280: 
Tl=l: 

GOSUB  4760: 
GOTO  4700 


4830  ’ PRAGMA 
4840  SOSUB  1400: 

IF  SIO'LIST"  GOTO  4850 
4845  GOSUB  4880: 

IF  T4=‘0N*  THEN  PLST=-1: 

LPR1NT  LPt; : 

RETURN  ELSE  IF  T$=’OFF’  THEN  PLST=0: 

RETURN  ELSE  E=6: 

GOTO  5020 

4850  IF  S4='CRT"  THEN  GOSUB  4880: 

IF  T*=,ON"  THEM  CLST=-1: 

RETURN  ELSE  CLST=0: 

RETURN 

4840  IF  SIO-INCLUDE*  THEN  RETURN  ELSE  GOSUB  1400: 
TO=LP: 

GOSUB  1940 

4870  IF  TOSC  THEN  E=9: 

GOTO  5020  ELSE  GOSUB  1230: 

60SUB  1400: 

T0=RP: 

GOSUB  1960; 

RETURN 

4880  GOSUB  1400: 

TO=LP: 

GOSUB  1960: 

T«=St: 

SOSUB  1400: 

T0=RP: 

60SUB  I960: 

RETURN 


4910  'MRITEPROC 
4920  T2=CP: 

T3=CB: 

CB=0: 

CP=(ADDR-1)I7*128: 

M=C1-1920: 

GOSUB  4030: 

M=LI: 

GOSUB  4030: 

M=P1: 

GOSUB  4030: 

M=LL: 

GOSUB  3990: 

CP=T2: 

CB=T3: 

RETURN 


4930  'CHEK  BOOL 

4940  IF  TVITSPIOTBOL  THEN  E=9: 

60T0  5020 
4950  TSP=TSP-1: 

RETURN 


4970  IF  TYITSPIOTINT  THEN  E=9: 

60T0  5020 
4980  TSP=TSP-1: 

RETURN 


4990  'MAX  OFFST 

5000  IF  OFST >HXOF  THEN  HXOF=OFST 
‘tO  RETURN 
GOSUB  5100: 

STOP 
5100  PRINT: 

PRINT'ERROR"|Ej'AT  LINE" ;LN: 
PRINT  BUFf : 

PRINT  TAB(B-l) ; 

RETURN 
5110  PRINT: 

PRINT  TOj "  EXPECTED’: 

GOSUB  5100: 

RETURN 


5200  'PROC  DEF 
5210  LL=LL+1: 
X=CPROC: 
60SUB  4280: 
X=OFSTs 
60SUB  4280: 
X=NX0F: 
GOSUB  4280: 
TO=ID: 

GOSUB  1950 
5220  GOSUB  5400: 
RETURN 


5300  'PROC  END  DEF 
5310  M=PEOP: 

GOSUB  3990: 
GOSUB  4300: 
P1=X: 

GOSUB  4300: 

ADDR=X: 

CPROC=X: 

L1=NX0F: 

C1=6C: 

GOSUB  4910; 
GC=GC+CP 
5320  LL=LL-1: 

GOSUB  5500: 
GOSUB  5600 
5330  GOSUB  4300: 
NXOF=X: 
GOSUB  4300: 
OFST=X: 
GOSUB  4300: 
CPROC=X: 
RETURN 


4960  'CHEK  INT 


(Continued  on  page  32) 
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0 

13 

CHARACTER, 4,1, ,2,, 

•END! . . 

0 

AND 

Listing  One 

0 

ARRAY 

16 

BEGIN 

(Listing  continued, 

19 

CASE 

text  begins  on  page  1 2) 

20 

22 

CONSTANT 

DECLARE 

26 

ELSE 

0 

ELSEIF 

28 

END 

5400  'PUSH  svns 

0 

EXIT 

5410  X=LEN<S* (SSP) ) : 

30 

FOR 

IP  1=255  THEN  SSP=SSP+1: 

0 

FUNCTION 

1=0 

0 

IF 

5420  GOSUB  4280: 

31 

IN 

X=SSP; 

0 

IS 

GOSUB  4280: 

0 

LOOP 

RETURN 

0 

LAST 

F ILEARRA,  5, 4, 0, ,  50, , 

LENGTH 

STRARRAY, 0,4,0, ,81,, 

MOD 

CHARRAY,2,4,0, ,2, , 

NOT 

5500  ’P0PSYNS 

INTARRAY, 1,4,0,  ,2, , 

NULL 

5510  GOSUB  4300: 

B00LARRA,4,4,0,,2,, 

OF 

FOR  1=01  TO  SSP: 

TRUE,4,0„-1,„ 

OR 

S«(I)=,,: 

FALSE, 4,0, ,0, , , 

OTHERS 

NEXT  I: 

MININT, 1,0, ,-32767,,, 

OUT 

SSP=X: 

NAXINT, 1,0, ,32767,,, 

PRAGMA 

S0SUB  4300: 

IN0UTF1L,5,4,0,,50,, 

PROCEDURE 

L0C2=X : 

KEYPRESS, 4, 3,,,, 40,0 

RETURN 

RETURN 

SEARCH, 1,3, ,,,39,0 

REVERSE 

5520  RETURN 

SIR, ,2, ,,,38,0 

THEN 

5600  S* (SSP)=RIGHT*<S«(SSP) ,L0C2+17) : 

VALUE, 1,3, ,,,37,0 

NHEN 

RETURN 

INITFILE,,2,,„36,0 

WHILE 

5700  S»(SSP)=RIGHT*<S«<SSP),L0C2): 

ASSIGN, ,2, ,,,35,0 

RETURN 

APPEND,, 2,,,, 34,0 

32767  END 

FREEMEN, ,2, ,,,33,0 

6ETNEN, 1,3,,,, 32,0 

End  Listing  One 

I0ERR0R, 1,3,  ,,,31,0 

PUTB00L, ,2, , , ,30,0 

SKIPLINE, ,2, ,,,29,0 

CHAR, 2,3, ,,,28,0 

NEXTNRIT, 1,3, ,,,27,0 

SETNRITE, ,2, , , ,26,0 

NEXTREAD, 1,3,  ,,,25,0 

Listing  Two 

SETREAD,,2,,,,24,0 

WRITE, , 2, , , , 23,0 

End  Listing  Two 

The  “ KEYWORDS.TXT "  data  file  is 

READ, ,2, ,,,22,0 

IS0PEN, 4, 3, ,,,21,0 

read  by  the  compiler  to  initialize  its 

RENAME, 1,3, ,,,20,0 

table  of  keywords  and  built-in  proce- 

ERASE, 1,3,,,,  19,0 

dures  and  functions.  The  numbers 

CLOSE, ,2,,,, 18,0 

near  the  beginning  of  the  file  are  read 

CREATE, ,2, ,,,17,0 

into  the  array  MAPf )  and  used  as  a 

OPEN, ,2, ,,,16,0 

hash  function  to  access  the  keywords 

SCANS, 1,3. , , , 15.0 

in  array  KEY$( ). 

SCANF, 1,3,, ,,14.0 

N0VERI6H, ,2, , , , 13,0 

* 

M0VELEFT, ,2, , , , 12,0 

Augusta  Keywords,  <C)Cop  "  Co«pute> 

SUBSTR, ,2,,,, 11,0 

15  Linguistics  1983 

POKE,, 2,,, ,10,0 

0 

PEEK, 1,3, ,,,9,0 

0123456789 

PUTSTR, ,2, , , .8,0 

01 23456789ABCDEF 

NEWLINE, ,2, , , ,7,0 

ABCDEF6HI JKLNNOPQRSTUVNXYZ 

PUTCHAR. ,2, , , .6,0 

abcdef ghi jklinopqrstuvxyxz 

6ETCHAR,  ,2,  ,,,5,0 

ABCDEFSHUKLHN0P8RSTUVHYXZ0123456789. 

PUTIN!,, 2,  „, 4,0 

1 

GETINT, ,2, , , ,3,0 

4 

PUTLINE, , 2, , , ,2,0 

GETSTR, ,2, , , , 1,0 

6 

STRING, 0,4,1,, 81,, 

7 

INTE6ER, 1,4, 1, ,2, , 

It 

0 

BOOLEAN, 4, 4,1, ,2,, 

32 
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RED 

A  Better  C  Screen  Editor,  Part  I 


RED  is  a  descendant  of  the  public- 
domain  text  editor  (called  ED2) 
which  I  described  in  the  January 
1982  issue  of  Dr.  Dobb’s  Journal.  I  started 
work  on  RED  so  that  .  I  could  edit  files 
without  worrying  how  large  they  were. 
RED’s  most  important  new  feature  is  a 
set  of  new  buffer  routines  which  remove 
all  restrictions  on  the  size  of  files  which 
may  be  edited. 

RED  appears  just  the  same  to  the 
user  as  does  ED2.  The  differences  between 
RED  and  ED2  are  all  under  the  covers, 
and  it  is  on  these  programming  details 
that  this  article  will  dwell.  Because  of  the 
length  of  RED’s  listing,  this  article  will  be 
split  into  two  parts.  This  month  I’ll  dis¬ 
cuss  how  RED’s  buffer  routines  work. 
These  routines  use  a  programming  tech¬ 
nique  called  virtual  memory,  which  I’ll 
explain  in  detail.  I’ll  also  discuss  a  new 
method  for  recovering  from  errors  which 
saves  a  lot  of  coding.  Part  I  of  this  article 
concludes  with  a  discussion  of  the  perfor¬ 
mance  of  RED’s  new  buffer  routines. 

The  new  buffer  routines  require 
unbuffered,  i.e.,  sector-at-a-time,  I/O 
routines.  Rather  than  write  my  own,  I 
decided  to  modify  the  assembly  language 
portion  of  the  BDS  C  run-time  library. 
Leor  Zolman,  the  author  of  BDS  C,  has 
generously  given  us  all  permission  to  use 
these  routines  in  any  way  we  choose. 
This  new  library  will  be  presented  in 
greater  detail  next  month  in  Part  II  of 
this  article. 

New  Buffer  Routines 

RED’S  new  buffer  routines  really  got 
started  when  I  bought  (for  8  dollars!)  a 
copy  of  the  “Just  Like  Mom’s  Editor” 
from  the  BDS  C  Users’  Group.  The  editor 
is  still  available  and  is  in  the  public  domain. 
I  would  like  to  thank  Scott  Fluhrer  and 
Neal  Somos  for  their  work  on  this  editor. 

RED’s  buffer  routines  are  direct 
descendants  of  the  buffer  routines  that 
Fluhrer  and  Somos  wrote.  After  a  few 
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hours  work,  I  converted  their  routines 
to  work  with  the  BDS  C  version  of  RED. 
I  quickly  discovered  two  problems  with 
the  code.  First,  though  files  larger  than 
memory  could  be  handled,  there  was  still 
a  limit  on  the  size  of  the  files.  Second, 
the  buffer  routines  did  not  keep  enough 
information  about  the  location  of  the 
current  line.  As  a  result,  scrolling  the 
screen  was  terribly  slow. 

This  was  the  start  of  what  has  be¬ 
come  four  new  versions  of  the  buffer 
routines.  I  used  the  excellent  BDS  C  com¬ 
piler  for  the  first  three  versions.  For  the 
fourth  version,  I  converted  the  buffer 
routines  from  BDS  C  to  Small  C.  Most  of 
the  conversion  work  consisted  of  chang¬ 
ing  structures  to  parallel  arrays. 

Now  let’s  see  how  the  new  buffer 
routines  work.  The  original  file  being 
edited,  the  user  file,  must  be  copied  to 
the  buffer  before  editing  can  be  done. 
When  editing  is  complete,  the  save  com¬ 
mand  or  resave  command  is  used  to  copy 
the  buffer  back  to  the  user  file. 

ED2’s  buffer  routines  kept  the  buf¬ 
fer  entirely  in  memory.  RED’s  buffer 
routines  keep  most  of  the  buffer  on  a 
disk  file,  the  work  file,  which  is  used  only 
by  the  editor;  the  work  file  is  created 
when  the  buffer  is  initialized  and  it  is 
erased  when  the  editor  ceases  execution. 

The  work  file  is  made  up  of  a  se¬ 
quence  of  fixed-length  blocks ;  it  is  not 
just  a  sequence  of  characters.  A  block  is  a 
multiple  of  the  sector  size  of  the  disk. 
(The  READ  _SIZE  constant  gives  the 
number  of  sectors  per  block.)  The  new 
buffer  routines  use  the  following  three 
operations  on  the  blocks  and  sectors  of 
the  work  file: 


sysseek  (fd,  block) 
int  fd,  block; 

Positions  the  file  whose  descriptor  is  fd 
to  the  indicated  block.  The  next  read 
or  write  operation  will  be  to  the  block. 
Sysseek ()  can  also  be  used  to  extend  the 
file,  i.e.,  to  increase  the  size  of  the  file. 
If  the  block  number  is  exactly  one  larger 
than  the  number  of  the  last  block  of  the 
file,  the  file  is  made  larger.  Some  operat¬ 
ing  systems  do  not  allow  files  to  be  made 
larger  dynamically.  They  require  that  the 
size  of  the  file  be  known  in  advance. 
However,  many  operating  systems  (in¬ 
cluding  Unix  and  CP/M )  do  allow  files  to 
be  extended  in  this  way. 


sysread  (fd,  buffer) 
int  fd; 

char  *  buffer; 

Reads  the  current  block  into  the  block - 
sized  buffer. 

syswrite  (fd,  buffer,  n): 
int  fd; 

char  *  buffer; 
int  n; 

Writes  n  sectors  from  the  buffer  to  the 
file.  When  writing  to  the  work  file,  n 
is  always  READ— SIZE.  Thus,  only  full 
blocks  are  ever  transferred  to  and  from 
the  work  file. 

The  operating  system  does  not  have 
to  provide  exactly  these  primitives,  but 
the  operating  system  must  make  it  possi¬ 
ble  to  write  them.  This  is  the  reason  for 
the  new  run-time  library  in  the  Small  C 
version  of  RED.  Next  month  I  will  dis¬ 
cuss  these  routines  in  more  detail. 


Inserting  and  Deleting  Blocks 

The  CP/M  operating  system,  like  most 
operating  systems,  does  not  allow  blocks 
or  sectors  to  be  inserted  into  the  middle 
of  a  file  or  deleted  from  the  middle  of  the 
file.  CP/M  does  allow  files  to  be  extended 
after  the  file  has  been  opened,  but  only  at 
the  end  of  the  file.  Thus,  when  sysseek  () 
extends  the  file,  the  newly  created  sectors 
must  follow  immediately  after  the  last 
sector  which  has  been  allocated. 

Fortunately,  these  restrictions  do  not 
really  prevent  the  editor  from  inserting 
and  deleting  blocks  where  required.  For 
most  purposes,  the  buffer  routines  can 
ignore  the  actual  location  of  each  block. 
The  buffer  routines  link  together  the 
blocks  in  a  list.  As  far  as  the  buffer  rou¬ 
tines  are  concerned,  the  first  block  in  the 
list  is  the  first  block  of  the  work  file, 
regardless  of  its  actual  location. 

Each  block  contains  two  pointer 
fields:  d_ next,  which  points  to  the  next 
block  on  the  list,  and  d_ back,  which 
points  to  the  previous  block.  Each  pointer 
is  an  actual  disk  address;  it  is  used  directly 
by  the  sysseek  primitive.  A  negative 
pointer  indicates  the  end  of  the  list.  Two 
global  variables,  b_ head  and  b_ tail,  point 
to  the  first  and  last  blocks  of  the  list. 

Figure  1  (page  35)  shows  a  typical 
list  of  blocks.  Links  are  shown  as  arrows, 
except  that  negative  links  are  shown  as  a 
slash.  The  values  in  the  link  fields  are  not 
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b-head 


b-tail 


Figure  1. 

The  blocks  of  the  work  file  form  a  double-linked  list. 


b-head  b-tail 


Deleting  blocks:  before 
Inserting  blocks:  after 


Figure  2a. 

Inserting  a  block  in  the  work  file  is  just  the  reverse  of  deleting  a  block. 


Deleting  blocks:  after 
Inserting  blocks:  before 

Figure  2b. 


shown  because  the  actual  location  of  each 
block  on  the  disk  does  not  matter.  The 
blocks  of  the  work  file  are  kept  on  a 
doubly  linked  list.  This  makes  inserting 
and  deleting  blocks  much  easier.  Searching 
the  list  backwards  is  also  made  possible. 

Figures  2a  and  2b  (at  left)  show 
how  to  insert  or  delete  blocks  from  the 
work  file.  To  delete  a  block,  the  pointers 
to  the  preceding  and  following  blocks  are 
changed  so  that  nothing  points  to  the 
deleted  block.  Figure  2a  shows  the  work 
file  before  the  block  is  deleted  and  Figure 
2b  shows  the  work  file  afterwards.  Insert¬ 
ing  a  block  is  essentially  the  reverse  of 
deleting  a  block.  Considering  Figures  2a 
and  2b  in  reverse  order  shows  how  a 
block  is  inserted  into  the  work  file. 

Deleting  the  last  block  of  the  work 
file  is  a  special  case,  illustrated  in  Figures 
3a  and  3b  (page  36).  However,  it  turns 
out  that  the  first  block  of  the  list  never 
changes.  It  is  never  deleted,  nor  is  a  block 
ever  inserted  before  it.  Thus,  the  b_head 
variable  never  changes; it  could  be  replaced 
with  the  constant  zero. 

By  now  it  should  be  obvious  that 
nothing  really  gets  deleted  from  the  work 
file.  Only  the  pointers  to  “deleted” 
blocks  are  erased.  In  order  to  keep  track 
of  all  deleted  blocks,  they  are  kept  on  a 
singly  linked  free  list.  The  global  variable 
b_free  points  to  the  first  block  of  the 
free  list.  Note  that  the  blocks  on  the  free 
list  are  still  part  of  the  work  file  as  far  as 
the  operating  system  is  concerned. 

All  changes  to  the  free  list  are  made 
at  its  head,  as  shown  in  Figures  4a  and  4b 
(page  38).  Figure  4a  shows  the  list  before 
a  block  is  deleted  while  Figure  4b  shows 
the  block  afterwards.  Inserting  a  block 
into  the  free  list  is  essentially  the  reverse 
process. 

When  inserting  a  block  into  the  work 
file,  a  new  block  is  taken  from  the  free 
list  if  the  free  list  is  not  empty.  Otherwise, 
the  sysseekQ  routine  is  used  to  allocate  a 
new  block  from  the  disk.  The  variable 
b_max_diskp  keeps  track  of  the  last 
block  that  has  been  allocated  to  the  work 
file.  Since  blocks  are  never  deallocated, 
this  variable  is  only  incremented,  never 
decremented. 


Inserting  and  Deleting  Lines 

We  have  just  seen  how  to  insert  and 
delete  entire  blocks.  Let  us  now  take  a 
closer  look  at  the  format  of  each  disk 
block  (see  Figure’ 5,  page  39).  A  block 
consists  of  an  8-byte  header  field  followed 
by  a  data  field.  The  header  contains  the 
two  link  fields,  d_next  and  d_back, 
which  we  have  already  discussed.  The 
header  also  contains  two  other  fields.  The 
d_lines  field  is  a  count  of  the  number  of 
lines  contained  in  the  data  field.  The 
d_avail  field  is  the  number  of  unused 
bytes  in  the  block. 
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Lines  are  not  split  across  blocks;  if  a 
block  is  not  big  enough  to  hold  another 
line,  one  or  more  lines  are  copied  to  a 
new  block.  Almost  all  blocks  contain  a 
few  unused  bytes,  but  this  is  not  a  great 
disadvantage.  (The  average  amount  of 
waste  in  a  block  is  one  half  of  the  average 
size  of  a  line.)  The  number  of  lines  in  the 
data  field  is  indicated  by  the  d —lines  field. 
Each  line  is  preceded  by  a  two-byte 
count  of  the  number  of  characters  in  the 
line.  No  end-of-line  character  is  used  in 
the  work  file;  thus,  the  net  overhead  due 
to  the  count  field  is  just  one  byte. 

To  delete  a  line  the  data  area  is  com¬ 
pressed  to  eliminate  the  line,  the  d —lines 
field  is  decremented,  and  the  d_ avail 
field  is  increased  by  the  length  of  the  line. 
Similarly,  to  insert  a  line  a  hole  is  made 
in  the  data  area  for  the  new  line,  the  new 
line  is  copied  into  the  hole,  and  the 
header  (the  d_ lines  and  the  d_ avail 
fields)  is  adjusted  to  reflect  the  change. 

Whenever  a  line  is  deleted,  a  check  is 
made  of  the  neighboring  blocks  to  see 
whether  any  blocks  can  be  merged.  Merg¬ 
ing  is  very  important  as  it  dfastically  re¬ 
duces  wasted  space  in  the  work  file.  Two 
blocks  are  merged  by  copying  the  data 
field  of  the  second  block  to  the  available 
area  of  the  first  block.  The  header  of  the 
first  block  is  adjusted  and  the  second 
block  is  deleted.  This  is  illustrated  in  Fig¬ 
ures  6a  and  6b  (page  39). 

Things  get  a  bit  complicated  if  there 
is  not  enough  room  in  the  block  for  an 
added  line.  There  are  three  cases  (see 
Figures  7a,  7b  and  7c,  page  43),  depend¬ 
ing  on  how  big  the  new  line  is  and  where 
in  the  block  the  new  line  goes.  Case  1 :  If 
the  new  line  will  fit  in  the  original  block, 
but  the  following  lines  will  not,  then  a 
new  block  is  created  for  the  following 
lines.  Case  2:  If  the  new  line  will  not  fit 
in  the  original  block,  a  new  block  is 
created  for  it.  If  the  following  lines  fit  in 
this  new  block,  they  also  are  copied  to 
the  new  block.  Case  3:  If  the  following 
lines  do  not  fit  in  the  new  block,  a  second 
new  block  is  created  just  for  them. 

Replacing  one  line  by  another  is 
done  simply  by  deleting  the  old  line  and 
inserting  the  new  line.  This  may  seem  a 
bit  slow,  but  the  delay  is  not  noticeable. 
More  importantly,  using  the  delete  rou¬ 
tine  in  this  way  insures  that  blocks  will 
be  merged  whenever  possible.  This  crude 
approach  to  replacing  lines  saves  a  lot  of 
code. 


Moving  through  the  File 

How  can  the  buffer  routines  find 
the  start  of  a  particular  line  in  the  work 
file?  This  creates  surprising  problems. 
When  I  first  designed  the  buffer  routines, 
I  planned  to  use  an  index,  an  array  of 
pointers  to  the  start  of  each  line.  I  did 
not  want  to  limit  the  index  to  what 
would  fit  into  memory  since  the  size  of 


the  index  would  then  limit  the  size  of  the 
file  that  could  be  edited.  (Many  editors 
which  purport  to  be  able  to  handle  large 
files  actually  suffer  this  limitation  includ¬ 
ing,  for  example,  the  editors  derived  from 
the  book  Software  Tools.)  I  considered 
putting  at  least  part  of  the  index  on  a  file. 
At  first  this  seemed  feasible,  but  in  fact  it 
is  not.  The  reason  is  that  the  index  must 
be  accessed  just  like  an  array:  given  a  line, 
we  want  to  find  the  pointer  to  the  line 
without  searching.  But  making  insertions 
or  deletions  to  an  array  requires  moving 
all  entries  in  the  array  which  follow  the 
inserted  or  deleted  entry.  This  is  much 
too  expensive  if  the  array  is  held  on  a 
disk  file. 

I  also  investigated  using  the  kinds  of 
data  structures  common  in  data  base 
management  systems.  An  example  is  the 


B-Tree.  (See  “The  Ubiquitous  B-Tree,” 
ACM  Computing  Surveys,  Volume  11, 
Number  2,  June  1979.)  The  basic  prob¬ 
lem  with  all  these  structures  is  that  they 
assume  that  the  key  associated  with  a 
data  item  is  fixed.  But  in  the  case  of  an 
editor,  a  data  item  is  a  line  of  text  and 
the  associated  key  is  the  line  number.  The 
line  number  changes  whenever  an  inser¬ 
tion  or  deletion  is  made  to  the  work  file. 
In  short,  I  can  find  no  way  to  adapt 
B -Trees,  or  any  similar  structure,  to  the 
problem  of  creating  an  index  for  a  text 
editor.  If  anyone  knows  of  a  way,  I  would 
love  to  hear  about  it.  (Aside:  in  some 
editors  the  line  number  of  a  line  does  not 
change  when  insertions  or  deletions  are 
made.  Such  editors  can,  and  do,  use  index 
files.) 

With  no  index  available,  the  buffer 
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routines  must  search  through  the  file 
block  by  block.  Surprisingly  enough,  this 
search  is  almost  always  very  fast!  There 
are  three  reasons  for  this: 

First,  the  requested  line  is  usually  very 
near  the  current  line.  In  fact,  most  often 
the  requested  line  is  either  the  immediately 
preceding  or  following  line.  For  example, 
when  scrolling  the  screen  or  when  using 
the  “find”  command,  the  editor  steps 
through  the  file  line  by  line. 

Second,  when  the  requested  line  is  far 
away  from  the  current  line  the  new  line  is 
most  often  near  either  the  beginning  or 
end  of  the  file.  The  beginning  and  ending 
blocks  of  the  work  file  can  be  accessed 
without  searching  because  the  editor  al¬ 
ways  keeps  track  of  where  they  are.  (This 
is  the  reason  for  the  b_max_line  and 
b _ tail  variables.) 

Third,  each  block  contains  a  count  of  the 
number  of  lines  in  the  block.  Thus,  it  is 
simple  to  tell  whether  a  block  contains 
the  desired  line  without  actually  search¬ 
ing  the  data  field  of  the  block. 

Virtual  Memory  and 
The  LRU  Algorithm 

Up  until  now  I  have  been  tacitly 
assuming  that  all  blocks  have  been  loaded 
into  memory  when  needed.  In  other 
words,  the  main  memory  appears  to  be  of 
unlimited  size.  Since  the  work  file  may 
grow  to  be  much  larger  than  the  available 
main  memory,  blocks  must  be  swapped 
into  and  out  of  memory  as  needed.  Here 
is  how  virtual  memory  works: 

The  buffer  routines  contain  a  set  of 
slots,  each  of  which  contains  one  block 
and  some  status  information  which  is  not 
saved  on  the  disk.  This  status  information 
tells  whether  the  slot  is  free  or  occupied, 
where  on  the  disk  the  block  is  stored,  and 
other  information  which  we  will  discuss 
a  little  later. 

Blocks  are  loaded  into  a  slot  only  by 
explicitly  calling  the  swap_in()  routine. 
Swap_in()  first  checks  to  see  whether 
the  requested  block  already  resides  in  a 
slot.  If  so,  swap_iri()  simply  returns  the 
slot’s  number.  Otherwise,  swap_in() 
searches  for  an  empty  slot.  If  one  is 
found,  the  requested  block  is  loaded  into 
the  empty  slot. 

If  no  empty  slot  is  found,  a  slot  must 
be  swapped  out  to  the  disk.  The  slot 
which  is  chosen  is  the  Least  Recently 
Used  (LRU)  slot.  Every  time  a  slot  is 
accessed  (i.e.,  every  time  swap_in()  is 
called),  the  d_lru  field  in  the  status  table 
is  adjusted  in  such  a  way  that  the  least 
recently  used  slot  has  the  highest  value. 
When  a  slot  must  be  swapped  out,  the 
slot  with  the  largest  d_lru  field  is  chosen. 

Once  the  slot  has  been  chosen,  the 
swap_in()  routine  checks  the  status  table 
to  see  if  the  block  has  been  changed  since 
it  was  loaded  into  the  slot.  This  informa¬ 
tion  is  popularly  called  the  dirty  bit. 


which  is  part  of  the  d_status  field.  The 
dirty  bit  is  cleared  when  a  block  is  first 
loaded  into  a  slot,  and  it  is  set  whenever 
the  block  is  changed.  If  the  dirty  bit  is 
set,  the  block  must  be  swapped  out  to  the 
disk  before  the  new  block  replaces  it. 
Otherwise,  the  new  block  can  be  loaded 
in  over  the  old  block  because  the  disk  still 
contains  a  correct  copy  of  the  old  block. 

Using  a  dirty  bit  complicates  the 
buffer  routines  quite  a  bit.  For  instance, 
failing  to  set  the  dirty  bit  properly 
creates  a  “time  bomb.”  The  code  appears 
to  work  correctly,  but  the  disk  contains 
an  incorrect  copy  of  a  block.  The  error 
only  shows  up  when  (possibly  much  later) 
the  block  is  reloaded  into  memory.  Tracy 
Kidder  discusses  this  problem  in  a  differ¬ 
ent  context  in  his  Pulitzer  Prize  winning 
book,  The  Soul  of  a  New  Machine.  (If 
you  haven’t  yet  read  it,  drop  everything 
and  do  so  at  once!)  In  spite  of  what  I 
have  just  said  about  the  dirty  bit,  using  it 
is  essential.  Without  the  dirty  bit,  many 
more  disk  accesses  will  be  needed. 

In  practice,  the  LRU  algorithm 
works  well.  It  eliminates  disk  accesses 
when  editing  in  a  localized  area,  which  is 
most  of  the  time.  It  also  performs  reason¬ 
ably  well  when  scrolling  through  the  file. 

It  is  instructive  to  compare  the  per¬ 
formance  of  the  LRU  algorithm  with  a 
simpler  approach.  For  example,  Figure  8 
(page  44)  shows  one  of  my  first  ideas  for 
creating  a  virtual  memory.  Briefly,  a  mem¬ 
ory  buffer  contains  just  a  few  lines.  All 
lines  before  these  lines  are  held  in  a  head 
file;  all  lines  after  the  lines  in  the  buffer 
are  held  in  a  tail  file.  The  advantage  of 
this  scheme  is  that  all  disk  activity  is  to 
the  physical  end  of  each  file.  This  method 
can  be  programmed  even  on  systems 
which  do  not  support  random  access  to 
files.  Also,  lines  are  changed  only  in  the 
main  buffer;  there  is  no  need  to  merge  or 
split  blocks. 

Using  two  files  in  this  way,  however, 
is  flawed.  Moving  through  the  file  requires 
that  lines  be  moved  through  the  memory 
buffer  and  written  to  one  of  the  two  files. 
For  instance,  moving  to  the  start  of  the 
file  requires  that  most  of  the  file  be  writ¬ 
ten  to  the  tail  file.  A  little  thought  should 
convince  you  that  the  performance  of 
this  method  is  essentially  the  same  as 
using  the  LRU  algorithm  without  the 
dirty  bit. 

Performance 

N+l  trivial  tasks  are  expected  to  be  accom¬ 
plished  in  the  same  time  as  N  trivial  tasks. 

—  Gray’s  Law  of  Programming 

N+l  trivial  tasks  take  twice  as  long  as  N 
trivial  tasks  for  N  sufficiently  large. 

—  Logg’s  Rebuttal  to  Gray’s  Law 

In  this  section,  I’d  like  to  compare 
the  speed  of  the  buffer  routines  used  in 
ED2  and  RED.  It  is  important  to  realize 


that  you  may  tune  the  performance  of 
RED’s  buffer  routines  by  changing  some 
compile  time- constants  defined  on  file 
red  10. sc  (see  Listing,  page  50).  The 
speed-up  may  be  dramatic,  depending  on 
your  disk  drives. 

In  general,  RED  will  run  faster  the 
more  buffers  there  are  and  the  larger  each 
buffer  is.  You  change  the  size  of  the  buf¬ 
fers  by  changing  the  DATA_SIZE  con¬ 
stant.  You  change  the  number  of  buffers 
by  changing  the  NSLOTS  constant.  If 
you  have  room  in  memory,  I  recommend 
setting  DATA—SIZE  to  1024  and  N- 
SLOTS  to  4  (or  more). 

Reading  a  file  into  the  buffer  is  al¬ 
ways  considerably  slower  with  these  new 
routines  because  the  file  being  edited 
must  be  copied  to  the  work  file.  The  im¬ 
portant  fact  is  that  large  files  are  loaded 
at  the  same  rate  as  small  files. 

Scrolling  the  screen  will  be  inter¬ 
rupted  from  time  to  time  when  the  LRU 
algorithm  swaps  blocks  in  and  out.  On  a 
floppy  disk  this  delay  is  slightly  annoying 
but  tolerable.  On  a  hard  disk  the  delay  is 
barely  noticeable.  In  any  event,  the  delay 
does  not  depend  on  the  size  of  the  work 
file,  but  rather  on  the  speed  of  the  disk 
drive,  the  block  size,  and  the  position  of 
the  work  file.  (The  closer  the  work  file  is 
to  the  directory,  the  better.) 

Inserting  or  replacing  lines  is  ex¬ 
tremely  fast,  unless  the  operation  results 
in  a  block  being  swapped  in  or  out.  For 
large  files,  these  operations  are  much 
faster  than  with  the  old  buffer  routines. 

Deleting  many  lines  can  take  longer 
with  these  routines  because  the  deleted 
blocks  must  still  be  written  to  the  disk  in 
order  to  keep  the  free  list  up  to  date. 

Keep  in  mind  that  splitting  or  joining 
blocks  usually  does  not  cause  blocks  to 
be  swapped  from  the  disk  because  the 
LRU  algorithm  increases  the  odds  that 
those  blocks  are  already  in  memory.  These 
operations  cause  little  overhead. 

Recovery  from  Errors 

The  new  buffer  routines  employ  two 
types  of  error  checking.  Whenever  a 
change  is  made  to  a  block,  a  check  is 
made  of  the  consistency  of  the  informa¬ 
tion  in  the  block’s  header  and  data  fields. 
These  checks  are  quite  effective;  almost 
all  bugs  in  the  code  were  caught  this  way. 
The  checks  have  even  pointed  out  a  bad 
memory  chip.  You  can  disable  these 
checks  by  commenting  out  all  the  calls  to 
check_biock()  on  file  redl2.sc.  I  don’t 
recommend  that  you  do  this  because  the 
checks  do  not  slow  down  the  editor  at 
all.  On  the  other  hand,  if  you  eliminate 
all  calls  to  check_block  ()  you  don’t  have 
to  #include  the  file  red  13. sc.  This  will 
save  you  some  space  if  you  really  need  it. 

The  other  type  of  error  checking  is 
reported  by  the  operating  system  to  the 
sysseekQ,  sysread(),  and  syswrite()  rou¬ 
tines.  Recovering  from  these  errors  is  a 
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difficult  problem.  Ideally,  the  editor 
could  keep  enough  information  around  to 
“back  out”  of  any  transaction  that  cannot 
be  completed,  but  this  cannot  be  done 
unless  a  truly  enormous  amount  of  infor¬ 
mation  is  passed  between  the  routines 
that  detect  errors  and  routines  that  might 
do  something  about  the  errors.  The  fol¬ 
lowing  paragraphs  discuss  the  three  main 
types  of  disk  error  and  how  RED  recovers. 

(1)  The  disk  becomes  full.  This  is  by 
far  the  most  likely  cause  of  a  disk  error. 
The  error  is  reported  on  the  screen  and 
the  operation  which  caused  the  error  is 
aborted.  The  buffer  is  cleared  if  the  load 
command  caused  the  error. 

(2)  The  disk  is  removed  during  editing. 

This  creates  a  real  problem  because  CP/M 
completely  botches  the  error  recovery. 
CP/M  gives  the  message,  “BDOS  error  on 
A:  select,”  then  proceeds  to  mark  the 
disk  as  read  only!  If  a  write  is  in  progress, 
CP/M  will  then  abort  the  editor  without 
ever  returning  control.  So  never  remove  a 
disk  while  RED  is  running. 

If  this  kind  of  error  should  happen 
to  you,  remember  that  the  disk  still  con¬ 
tains  a  copy  of  the  work  file.  To  recover 
the  information  from  the  work  file  do  the 
following: 

•  Rename  the  work  file  so  that  you  don’t 
erase  it  by  invoking  the  editor! 

•  Write  a  short  recovery  program.  This 
program  should  be  patterned  after  the 
write_file()  routine  in  file  red  12. sc. 
The  recovery  program  should  copy  the 
work  file  to  another  file  deleting  header 
information  as  it  goes.  Note  that  block 
0  of  the  work  file  always  contains  the 
first  block  of  the  file,  but  the  follow¬ 
ing  blocks  may  be  anywhere  in  the 
work  file.  Use  the  d_next  field  in  the 
header  of  each  block  to  tell  where  the 
next  block  is  to  be  found. 

(3)  There  is  a  “real”  disk  error.  In 
other  words,  the  hardware  that  controls 
the  disk  fails  to  read  or  to  write  a  sector 
properly.  Some  case  could  be  made  for 
retrying  the  read  or  write  operation  a  few 
times  to  see  if  the  problem  would  go  away. 
In  my  experience,  this  kind  of  problem  is 
very  rare,  so  the  buffer  routines  don’t 
attempt  any  fancy  recovery.  Besides, 
accessing  the  disk  further  might  just  com¬ 
pound  the  problem.  The  best  thing  to  do 
is  to  stop  editing  and  start  figuring  out 
why  the  disk  error  has  occurred. 

In  short,  the  new  buffer  routines 
are  probably  more  reliable  than  the  old 
routines.  Even  in  an  extreme  emergency, 
the  work  file  may  be  used  to  recover 
your  work. 

In  the  ED2  editor,  errors  were  indi¬ 
cated  by  returning  a  status  value  from  all 
buffer  routines.  In  RED,  this  is  done  by 


setting  three  disk  restart  points  —  one  for 
each  mode  that  the  editor  can  be  in. 
When  a  disk  error  occurs,  the  longjmpQ 
function  (defined  in  the  BDS  C  library)  is 
used  to  perform  a  jump  to  the  current  re¬ 
start  point.  Here  is  an  example  of  a  goto 
instruction  being  justified  on  the  basis  of 
eliminating  a  lot  of  extraneous  code. 

Summary 

To  summarize  the  important  features 
of  RED’s  new  buffer  routines: 

•  Huge  files  may  be  edited  because  main 
memory  contains  no  data  structures 
whose  size  depends  on  the  size  of  the 
file.  In  addition,  the  work  file  never 
contains  much  garbage  -  typically,  the 
work  file  is  no  more  than  10%  larger 
than  the  original  file  being  edited. 
Files  are  limited  in  size  only  by  (1) 
how  much  room  exists  on  the  disk  for 


the  work  file  and  (2)  how  large  the 
operating  system  allows  a  file  to  be. 

•  The  response  time  for  editing  is  con¬ 
stant.  Inserting,  deleting,  or  replacing  a 
line  takes  the  same  time  regardless  of 
the  length  of  the  file  being  edited.  I 
have  edited  files  of  20,000  lines  easily. 

•  The  response  time  for  file  operations  is 
linear.  Reading,  writing,  and  appending 
files  proceed  at  a  constant  rate,  regard¬ 
less  of  the  size  of  the  files.  In  other 
words,  reading  a  10,000  line  program 
takes  only  10  times  longer  than  read¬ 
ing  a  1,000  line  program. 

Next  month  I’ll  discuss  the  Small  C 
library  used  in  RED  and  improvements 
that  might  be  made  to  RED.  1’U  also 
say  a  few  words  about  why  RED  is  copy¬ 
righted. 


b-free 


Deleting  blocks:  after 
Inserting  blocks:  before 

Figure  4a. 

All  insertions  and  deletions  are  made  at  the  head  of  the  free  list. 


b-free 


Deleting  blocks:  before 
Inserting  blocks:  after 

Figure  4b. 
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start  of  buffer 


end  of  buffer - 1 


memory  buffer 


end  of  file 


tail  file 

(written  backwards) 


END  of  file 


Figure  8. 

An  alternative  way  of  providing  a  huge  buffer.  This  method  causes  many  extra  disk  accesses. 


Figure  5. 

A  block  consists  of  a  header  field,  which  tells  what 
is  stored  in  the  block,  and  the  data  field,  which  con¬ 
tains  lines  of  text. 


Figure  6b. 

Two  blocks  after  merging.  Lines  are  copied  from  the 
second  block,  the  header  of  the  first  block  is  adjusted 
and  the  second  block  is  deleted. 
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header  1 


header  2 


preceding 

lines 


new  line 


following 

lines 


old  block 

new  block 

(a) 

header  1 


header  2 


new  line 


preceding 

lines 


following 

lines 


old  block 

new  block 

(b) 

header  1 


header  2 


header  3 


preceding 

lines 


new  line 


following 

lines 


old  block 


first  new  block 

(c) 


second  new  block 


Figure  7. 

In  (a),  the  new  line  fits  into  the  old  block;  (b)  shows  both  the  new  line  and 
the  following  lines  fitting  into  the  new  block;  and  (c)  shows  two  new  blocks 
created. 


Dr.  Dobb’s  Journal,  Number  81,  July  1983 


43 

367 


RED  ■  Listing 

(Text  begins  on  page  34) 


/» 

Include  file  for  RED:  small-C  version 


So  ur ce  :  red . sc 
Version:  January  20,  1983 


Copyright  ( C) 

1  983 

by  Ed  war  d  K .  Ream 

/'include 

a  :  r  ed  0  .  sc 

/» 

constants,  (system)  globals 

*/ 

//include 

a  :  r  ed  1  .  sc 

/• 

user  defined  globals 

•  / 

//include 

a : r  ed  2 . sc 

/» 

main  program 

•/ 

»>  include 

a : r  ed  3 • sc 

/* 

command  mode  commands 

•/ 

"include 

a : r  ed  4 . sc 

/• 

edit  mode  module 

«/ 

"include 

a : r  ed5 . sc 

/  * 

output  format  module 

*  / 

"include 

a : r  ed  6 . sc 

/* 

display  screen  module 

*  / 

//include 

a : r  ed  7 . sc 

/  * 

prompt  line  module 

•/ 

//include 

a : r  ed  8 . sc 

/  « 

operating  system  module 

«  / 

/'include 

a : r  ed  9 . sc 

/« 

utility  routines 

«/ 

/'include 

a : r  ed 1 0 . sc 

/• 

buffer  module  --  part  1 

«  / 

/'include 

a : r  ed  1  1  .  sc 

/  * 

--  part  2 

•  / 

"include 

a  :  r  ed  1  2  .  sc 

/  * 

--  part  3 

»/ 

/•include 

a : r  ed 1 3 • sc 

/  * 

debugging  routines 

*  / 

"include 

a :l ib  1 

/  * 

machine  library 

*/ 

"include 

a  :  1  i  b  2 

/  * 

init,  exit,  utility  library 

•/ 

"include 

a : fiolibl 

/  • 

file  library 

*/ 

"include 

a  :  x  1  i  b 

/• 

setjmp,  longjmp 

•/ 

RED's  non-user  defined  globals  --  small-C  version 

So  urce :  redo . sc 
Version.  3ee  below 

Copyright  (C)  1983  by  Edward  K.  Ream 

•  / 


/*  Define  global  constants  */ 


//define 

SIGN0N 

"Welcome  to 

RED" 

/'define 

VERSION 

"Small-C  Version  4.04,  February  27, 

1  983" 

//define 

COPYRIGHT  "Copyright  (C)  1983  by  Edward  K.  Ream" 

/'define 

XSIGN 

"Type 

'help' 

in  command  mode  for  help" 

//define 

XSIGN 1 

"Type 

'  h '  in 

edit  mode  for  more  help" 

/•  Define  constants 

describing  a  text  line  •/ 

/'define 

MAXLEN 

200 

/  • 

max  chars  per  line 

*/ 

"def i ne 

MAXLEN 1 

201 

/• 

MAXLEN  ♦  1 

*/ 

/•  Define  operating 

system 

constants  * / 

//define 

SYSFNMAX  15 

/• 

CP/M  file  name  length  ♦  1 

»/ 

"define 

C  PM  EOF 

26 

/*  Define  misc. 

constants  * 

/ 

/'define 

EOS 

0 

/• 

code  sometimes  assumes  \0 

«/ 

//define 

OK 

1 

"define 

ERR 

-  1 

/* 

error.  must  be  <0 

•/ 

"define 

ERROR 

-1 

/* 

error .  must  be  <0 

«/ 

"define 

EOF 

-2 

/• 

end  of  file.  must  be  <0 

•/ 

"def  ine 

YES 

1 

/* 

must  be  nonzero 

•/ 

"define 

NO 

0 

"define 

CR 

13 

/* 

carriage  return 

*/ 

"define 

LF 

1  0 

/• 

line  feed 

•/ 

"define 

TAB 

9 

/* 

tab  character 

*/ 

"define 

HUGE 

32000  /• 

practical  infinity 

•/ 

FED  special  key  definitions 
Source  :  red  1 . sc 

This  file  was  created  by  the  configuration  program: 
January  20,  1  98  3 • 


Define  which  keys  are  used  for  special  edit  functions. 

*  / 


" d ef  ine 

U  P  1  10 

" d  ef ine 

DOWN  1 

13 

"define 

UP2  21 

"define 

DOW  N  2 

’  4 

"define 

LEFT  1 

12 

"define 

RIGHT1  18 

//  d  e  f  i  n  c 

INS  1 

14 

"define 

EDIT  1 

5 

"define 

ESC  1 

27 

tfdef ine 

DEL  1 

8 

"define 

Z  A  P  1 

26 

"define 

ABT  1 

24 

"define  SPLT1  19 
//define  J0IN1  16 
II  define  REP1  1 

/* 

Define  length  and  width  of  screen  and  printer. 

»/ 

//define  SCRNW  80 
/(define  SCRNW1  79 
/(define  SCRNL  24 
/(define  SCRNL  1  23 
//define  SCRNL2  22 
/(define  LISTW  132 


RED  operating  system  module  --  small-C  version 

Source:  red  8 . sc 

Version:  January  23.  1983 

Copyright  (C)  1983  by  Edward  K.  Ream 


/*  Define  globals  used  by  this  module  *  / 


char  sysi nbuf [ 1 28  ]  ; 
int  sysi ncnt ; 


/•  file  buffer  »/ 
/•  buffer  count  */ 


char  syscbuf [ MAXLEN ] ;  /*  console  type  ahead  buffer  */ 

int  sy scent ; 


int  sysrent; 
int  syslastc; 


/*  repeat  count  */ 

/*  last  character  (may  be  repeated)  */ 


int  systopl , sy stopy , sy snl ;  /*  interrupt  information  */ 

//define  READ  SIZE  4  /*  see  also  definition  in  red10.se  */ 


/*  Initialize  the  system  module.  *  / 

sys i n i t ( ) 

l 

sysnl  s  0; 
sysccnt  =  0; 
sysrent  =  0; 
syslastc  =  0; 

} 


/* 


Save  info  for  interrupted  screen  update. 


sysintr (systl ,  systy,  sysn) 
int  systl,  systy,  sysn; 
l 

systopl  =  systl  ; 
systopy  =  systy; 
sysnl  =  max ( 0 , sy sn ) ; 

} 


Return  -1  if  no  character  is  ready  from  the  keyboard. 
Otherwise,  return  the  character. 


This  routine  handles  typeahead  and  the  repeat  key. 


syscstat(  ) 


int  c  ,  i  ; 


/•  Always  look  for  another  character, 
c  =  bdos(6,-1); 


if  (  (c  =s  REP1)  &  (syslastc  !=  0)  )  { 
sysrent  =  max ( 1 ,  2*sysrcnt) ; 


i  =  0; 

while  (  (i+  +  <  sysrent)  &  (sysccnt  <  MAXLEN)  )  l 

syscbuf  tsysccnt++]  =  syslastc; 

1 

) 

else  if  ( c  ! =  0)  { 

syslastc  s  c; 
sysrent  =  0; 
syscbuf  [sysccnt**]  =  c; 

) 

if  (sysccnt  >  0)  { 

return  syscbuf  [ — sysccnt]; 


else  { 

} 


return  -  1 ; 


(Continued  on  page  48) 
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Wait  for  next  character  from  the  console. 

Do  not  ec ho  it  . 

This  routine  prints  any  waiting  lines  if  there  is  no 
input  ready 


sysc i n (  ) 

( 


i  nt  c ; 

while  ( ( c  =  syscstat( ) )  =  =  -1)  { 

/*  Output  queued  ?  */ 
if  ( sysnl  >  0)  { 

buf out ( sys topi ,  systopy,  sysnl); 

) 


Wait  for  all  console  output  to  be  finished. 


whi le  ( sysnl  >0)  { 

bufout ( systopl ,  systopy,  sysnl); 

} 


/*  Print  character  on  the  console.  */ 


syscout ( c ) 
char  c; 


bd os ( 6 , c  )  ; 
r  et  ur  n ( c ) ; 


/*  Print  one  character  on  the  printer.  */ 
syslout ( c  )  char  c ; 


sysopen ( name ,  mode) 
char  *  name ; 
i  nt  mode ; 


/*  Kludge:  set  count  for  sysgetc().  »/ 
if  (mode  ==  0)  { 

sysincnt  =  128 ; 

} 

return  open(name,  mode); 


Read  next  line  from  a  file. 

End  the  line  with  a  zero  byte. 

Only  one  file  at  a  time  may  use  this  routine 


sysrdlnf f ile ,  buffer,  maxlength) 
i nt  file; 
char  *  buffer; 
int  maxlength; 

{ 

int  c ,  count  ; 

count  =  0; 

whi le( 1 )  { 

c  =  sysgetc(file); 

if  (c  ==  CR)  { 

continue ; 

) 

else  if  (c  ==  CPMEOF)  ( 

buffer  [count  =  EOS]; 
return  ERROR ; 

) 

else  if  (c  ==  LF)  [ 

buffer  [count]  =  EOS; 
return  count; 

} 

else  if  (count  <  naxlength  -  1)  { 
buffer  [count**]  =  c; 


Get  one  character  from  the  input  file. 

Only  one  file  at  a  time  may  use  this  routine. 


bdos( 5 , c ) ; 
r etur n ( c ) ; 


/*  Close  a  file  which  was  opened  by  sysopen()  or  syscreat().  */ 

sysclose( file) 
int  file; 

\ 

return  close(file); 


Create  a  file.  Erase  it  if  it  exists. 
Leave  the  file  open  for  read/write  access. 


syscreat( filename) 
char  *  filename; 


sys  getc ( file) 
int  file; 

{ 

int  n  ; 


return  cr ea t ( f i 1 ename ) ; 


if  (sysincnt  ==  128)  { 

n  =  read(file,  sysinbuf,  1); 
if  (n  ==  ERROR)  { 

d  i  s k_e rr or ( "read  error"); 
return  CPMEOF ; 

1 

else  if  (n  =  =  0)  [ 

/*  End  of  file.  */ 
return  CPMEOF ; 

} 

else  { 

sysincnt  =  0; 

) 

) 

return  sysinbuf  [ s y s i ncn t+ + ] ; 


Return  YES  if  the  file  exists.  *  / 


sysexists( filename) 
char  *  filename; 


if  ((file  =  open( filename ,  0))  !=  ERROR)  { 

close ( file) ; 
return  YES; 

} 

else  { 

return  NO; 

} 


Open  a  file  which  already  exists. 
Mode  0  —  read  only. 

Mode  1  —  write  only. 

Mode  2  —  read/write. 


Read  one  block  (READ  SIZE  sectors)  into  the  buffer. 


sysread ( f i 1 e ,  buffer) 
int  fi le ; 
char  *  buf  f er ; 


return  read(file,  buffer,  READ  SIZE); 


Write  n  sectors  from  the  buffer  to  the  file.  *  / 


syswr i te ( f i 1 e ,  buffer,  n) 
int  f i le ; 
char  *  buffer; 
int  n ; 


(Continued  on  page  50) 
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(Listing  continued,  text  begins  on  page  34) 

return  write(file,  buffer,  n); 


b_head ; 
b_tai 1 ; 
b_n3x_diskp ; 

b_da  ta_f  d ; 
b_u  se  r_f  d ; 
b  free; 


/*  first  block’s  disk  pointer  */ 
/*  last  block's  disk  pointer  */ 
/“  last  sector  allocated  “/ 

/*  file  descriptor  of  data  file  */ 
/*  file  descriptor  of  user  file  “/ 
/“  head  of  list  of  free  blocks  “/ 


bbuff  [ DATA_SIZE] ; 


temporary  buffer. 


Seek  to  a  specified  block  of  an  open  file.  */ 


sysseekCfile,  block) 
int  file,  block; 


return  seek(file,  block  *  READ  SIZE,  0); 


Remove  the  file  from  the  file  system.  “/ 


ysunlink(filename) 
r.ar  *  filename; 


return  un 1 i nk ( f i 1 e name ) ; 


*  Check  file  name  for  syntax.  */ 

syschkfn(args)  char  *args; 

{ 

return(OK) ; 

} 

/*  Copy  file  name  from  args  to  buffer.  */ 
sysccpf n ( arg s , buf f er )  char  "args,  “buffer; 


n=  0 ; 

while  C n< (SYSFNMAX-1  )  )  { 

if  (  args[  n] =  =  E0S)  l 
break; 


buf  fer [ n] =args[ n]  ; 
n*  + ; 


Partially  define  the  format  of  a  block.  The  data 
field  is  organized  as  a  singly  linked  list  of  lines; 
that  is,  each  line  is  preceded  by  a  two-byte  length 
field. 

The  d_back  and  d  next  fields  in  the  header  are  used 
to  doubly-link  tJTe  disk  blocks  so  that  stepping 
through  the  blocks  either  forward  or  backwards  is 
efficient.  -1  denotes  the  end  of  each  list. 

When  blocks  become  totally  empty  they  are  entered 
on  a  list  of  free  blocks.  The  links  of  this  list 
are  kept  in  the  blocks  themselves  in  the  d_next  field. 
The  b_free  variable  is  the  head  of  this  list. 

Also  define  the  in-core  block  table.  This  table 
contains  the  blocks  that  have  been  swapped  into 
memory.  Each  entry  in  this  table  is  called  a  slot. 


/*  comment  out  - 

struct  BLOCK  { 

int  d_b 

int  d_n 

int  d_a 

int  d_l 

char  d  d 

Id  blocks  [NSLOTSl; 


d_bac  k ; 
d_nex  t ; 
d_a vai 1 ; 
d_lines ; 

d  data  [BUFF  SIZE] ; 


end  comment  out 


buf fer [ n] =E0S  ; 


//define  HEADER_S  IZE  8 
//define  BUFF_SIZE  504 
(/define  SLOT  SIZE  2560 


int  d_bac  k  [NSLOTS]; 
int  d_nex  t  [NSLOTS]; 
int  d_a vai 1  [NSLOTS]; 
int  d_l ines  [NSLOTS]; 
char  d  data  [SLOT  SIZE]; 


/*  size  of  first  4  fields  */ 
/•  DAT  A_S IZE  -  H  EA  DE  R_S IZE  »/ 
/»  NSLOTS  *  DATA  SIZE  »/ 


/  *  II  of  previous  block  *  / 
/*  H  of  next  block  */ 
/*  II  of  data  bytes  free  “/ 
/*  II  of  lines  on  block  *  / 
/*  resident  blocks  */ 


De  f i ne 

the  resident 

status 

table  . 

1982;  January  23.  1983 

»/ 

There 

is  one  entry 

for  each 

slot. 

by  Edward  K.  Ream 

H d  ef i ne 

FREE 

1  /» 

status  : 

block 

i  s 

avai lable 

»/ 

#def ine 

FULL 

2  /• 

status  : 

block 

is 

al located 

•/ 

//define 

DIRTY 

3  /» 

status  : 

must 

swap 

out 

*  / 

RED  buffer  routines  --  small-C  version 
Part  1  —  goto,  output  and  status  routines. 


Source:  red10.sc 


You  may  tune  these  constants  for  better  performance. 

DATA_S IZE :  The  size  of  struct  BLOCK. 

Make  sure  that  DATA_SIZE  is  a  multiple 
of  the  size  of  your  disk  sectors. 

(for  CP/M,  a  multiple  of  128) 

Make  sure  that  the  READ_SIZE  constant  in 
ed 8 . c  is  DAT A_S IZE  /  128. 

NSLOTS:  The  number  of  BLOCKS  resident  in  memory. 

The  code  assumes  this  number  is  AT  LEAST  3. 

DATA_FILE:  The  name  of  the  work  file.  Note  the  double 

quotes.  Pick  a  name  you  never  use. 


comment  out 


struct  STATUS  { 

int  d_lru; 

int  d_status; 

int  d_d i sk  p ; 

}  d  stat  tab  [NSLOTS]; 


end  comment  out  */ 


d_lr u  [NSLOTS]; 
d_status  [NSLOTS]; 
d_di skp  [NSLOTS]; 


/ *  lr u  count  *  / 
/»  FULL,  FREE  or  DIRTY  »/ 
/“disk  pointer  “/ 


//define  D  AT  A_S  I  Z  E  512 
//define  NSLOTS  5 

(/define  DATA_FILE  "@@data?@.tmp" 

/*  Do  not  touch  this  constant.  »/ 
//define  CPM  SIZE  128 


b_f  at  a  1  ; 
b_c  flag; 

b_l i n  e ; 
b_max_line; 
b_  1  i  n  e  p  ; 

b_slot ; 
b  start; 


/*  erase  buffer  on  disk  error 
/“  buffer  changed  flag 

/*  current  line  number 

/*  highest  line  number 

/“  pointer  to  line  (local  var) 

/*  current  block's  slot  number 

/*  first  line  of  current  block 


Boundary  conditions: 

1.  Only  buf ins( )  can  extend  the  buffer,  NOT 
bufgo()  and  bufdn(). 

2.  bufatbot()  is  true  when  the  current  line  is 
PASSED  the  last  line  of  the  buffer.  Both 
bufgo()  and  bufdn()  can  cause  bufatbot()  to 
become  true.  bufgetln()  returns  a  zero  length 
line  if  bufatbot()  is  true. 

3.  b_max_line  is  the  number  of  lines  in  the  buffer. 
However,  b_line  ==  b_max_line  +  1  is  valid  and 
it  means  that  b_line  points  at  a  null  line. 


50 

370 


Dr.  Dobb’s  Journal,  Number  81,  July  1983 


<4.  All  buffer  routines  assume  that  the  variables 
b_slot,  b_line  and  b_start  describe  the 
current  line  when  the  routine  is  called.  Thus, 
any  routine  which  changes  the  current  line  must 
update  these  variables. 

*/ 


/*  Return  YES  if  at  bottom  of  buffer  (past  the  last  line).  */ 
buf  a  tbot (  ) 

I 

return  (b_line  >  b_max_line); 

) 


/•  Return  YES  if  at  top  of  buffer.  */ 

bufattop(  ) 

( 

return  (b  line  =  =  1); 

J 


/*  Return  YES  if  the  buffer  has  been  changed.  */ 

bufchng (  ) 

( 

return  b_cflag ; 

) 


/*  Move  towards  end  of  buffer.  */ 

b  u  f  d  n  (  ) 

( 

/*  The  call  to  buf_gofw()  instead  of  bufgoC) 

•  is  made  purely  to  increase  speed  slightly. 

»/ 

if  (bufatbotO)  { 
return  ; 

} 

else  { 

b_l  i  ne-f  +  ; 
buf_gof w( ) ; 


/•  Clean  up  any  temporary  files.  */ 

b u f  e  nd  (  ) 

{ 

sysunlink(DATAFILE); 

1 


/« 

Go  to  line  n . 

Set  bslot,  b_line,  b_start. 

•/ 

buf  go ( n ) 
i  nt  n  ; 

{ 

int  distance,  oldline; 

/*  Put  the  request  in  range.  */ 
old  line  =  b_line ; 

b_line  =  min  (n,  b_max_line  +  1); 

b_line  =  max  (1,  b_line); 
distance  =  b_line  -  oldline; 

if  (distance  ==  0)  { 

/*  We  are  already  at  the  requested  line.  *  / 
return  ; 

) 

else  if  (distance  =s  1)  { 

/*  Go  forward  from  here.  */ 
buf_gof w( ) ; 
return  ; 

) 

else  if  (distance  ==  -1)  { 

/*  Go  back  from  here.  */ 
bu  f_gobk ( ) ; 
return  ; 

} 

else  if  (distance  >  0)  { 
if  (  b_line  > 

oldline  +  ((b_max_line  -  oldline)  /  2) 
)  { 


) 


) 

else 


/*  Search  back  from  end  of  file.  */ 
swa p_i n ( b_tai 1 ,  &b_slot); 
b_s  tart  = 

1  +  b_max_line  -  d_lines  [b_slot]; 
b uf_gobk(  )  ; 
return  ; 

} 

el  se  { 

/*  Search  forward  from  here.  */ 
buf_gofw( ) ; 
return  ; 

} 


if  ( b_ 1 i n e  <  oldline  /  2)  { 

/*  Search  from  start  of  file.  */ 
s wa p_i n ( b_hea d ,  &b_slot); 
b_start  =  1; 

buf_gof w( ) ; 
return; 

1 

el  se  { 

/*  Search  back  from  here.  */ 
buf_gobk( ) ; 
return ; 

) 


/* 

Search  backwards  from  block  for  b_line. 

The  starting  line  number  of  the  block  is  b_start. 
Set  b_slot  and  b_start. 

•/ 

buf_gobk  (  ) 

{ 

int  diskp; 

if  (  ( b_s lot  =  =  ERROR)  | 

(b_start  <  1)  !  (b_start  >  b_max_line)  1 

(b_line  <  1)  !  (b_line  >  bmaxline  +  1) 

)  ( 

cant_happen ( "buf_gobk  1"); 

) 

/*  Scan  backward  for  the  proper  block.  */ 
while  (b_start  >  b_line)  { 

/•  Get  the  previous  block  in  memory.  */ 
diskp  =  d_back  [b_slot]; 
if  (diskp  ==  ERROR)  { 

can t_happen ( "buf_gobk  2"); 

} 

swap_i n( diskp ,  &b_slot); 


) 


/*  Calculate  the  start  of  the  next  block.  */ 
b_start  =  b_start  -  d_lines  [b_slot]; 
i f  ( b_start  <=  0 )  { 

can t_happen ( "buf_gobk  3"  )  I 

) 


/* 

Search  forward  for  line  n. 

Set  b_slot  and  b_start. 

*/ 

buf_gofw  (  ) 

l 

int  diskp; 

/*  The  last  line  is  always  null.  */ 
if  ( buf  a  tbo t ( ) )  { 
return  ; 

) 


if  (  (b_slot  ==  ERROR)  !  (b_start  <  b_start)  ! 

(b_start  <  1)  !  (b_start  >  b_max_line)  ! 

(bline  <1)  !  (b  line  >  b  max  line  +  ') 


can t_h ap pen ( " bu f_gof w  1"); 


/*  Scan  forward  to  the  proper  block.  *  / 
while  (b_start  +  d_lines  [ b_s lot]  <=  b_line)  ( 

/*  Get  the  start  of  the  next  block.  */ 
b_start  =  b_start  +  d_lines  [  b_slot] ; 

/*  Swap  in  the  next  block.  */ 
diskp  =  d_next  [b_slot]; 

if  ((diskp  ==  ERROR)  !  (b_start  >  b_ma x_l i n e ) ) { 
cant_happen ( " buf  gofw  2"); 

{ Continued  on  next  page ) 
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(Listing  continued,  text  begins  on  page  34) 

s wa p_i n ( di skp ,  &b_slot); 


/•  Return  the  current  line  number.  */ 

buf  1 n(  ) 

{ 

return  b_l ine  ; 

1 


/»  Initialize  the  buffer  module.  */ 
t  u  f  n  e  w  (  ) 

i  nt  i  ; 

char  *  static ; 


Initialize  b_data_fd  on  the  first  call 
to  this  routine.  A  kludge  is  required 
because  small-C  has  neither  real  static 
variables  nor  initializers. 

•/ 


outxyCO,  topy++); 
bufoutln(  topline-*-*-)  ; 
n 1 i ne  s-- ; 

sysintrftopline,  topy,  nlines); 
break  ; 

) 

out  x  y ( x , y ) ; 
b uf  go ( 1 ) ; 


/*  Print  one  line  on  screen.  */ 

bufoutln(  line) 
i nt  line; 

{ 

char  buffer  [MAXLEN1]; 
i  nt  n ; 

buf  go(  line)  ; 
i f  ( buf  a  tbot (  ) )  { 

outdeol (  )  ; 

} 

else  { 

n  =  bufgetlnf buf fer  ,  MAXLEN); 
n  =  min ( n  ,  MAXLEN); 
buf  fer  [ n ]  =  C  R  ; 
f mtsout ( buf f er  ,  0); 
outdeol (  )  ; 

) 

} 


1 


static  = 

i f  ( “static  =  =  0)  { 

•static  s  1; 
b_data_fd  =  ERROR; 

} 

/•  The  free  list  is  empty.  •/ 
b_free  =  ERROR; 

/•  Free  all  slots.  •/ 
i  =  0; 

while  (i  <  N  SLOTS )  { 

d_status  [i]  s  FREE; 
d_lru  [ i ]  *  i  ; 
d_d i s k p  [i]  r  ERROR; 
i-*-*- ; 

} 

/•  Allocate  the  first  slot.  •/ 
b_slot  =  b_head  =  b_t  a i 1  =  0; 
b_max_disp  =  1 ; 

d_diskp  [b_slot]  z  0; 
d_status  [b_slot]  z  DIRTY; 

d_back  [b_slot]  z  d  next  [b_slot]  s  ERROR; 

/•  The  first  slot  is  empty.  •/ 

d_lines  [b_slot]  =  0; 

d_a vai 1  [b_slot]  z  BUFF_SIZE; 

/*  Make  sure  temp  file  is  erased.  •/ 
if  ( b_data_f d  !z  ERROR)  { 

sysclose( b_data_fd ) ; 
b_da  ta_f  d  =  ERROR; 
sysunl ink( DATA_FILE) ; 

} 

/•  Set  the  current  and  last  line  counts.  •/ 
b_line  =  1; 
b_nax_line  =  0; 
b_start  z  1; 

/•  Indicate  that  the  buffer  has  not  been  changed.  */ 
b_cflag  z  NO; 


/•  Replace  current  line  with  the  line  that  p  points  to. 
*  The  new  line  is  of  length  n. 


bufrepl ( line ,  n) 
char  line  [  ]  ; 
i  nt  n  ; 

{ 

/•  Do  not  replace  null  line.  Just  insert.  •/ 
i f  ( buf  a  tbot (  ) )  { 

buf ins(  line  ,  n); 
return  ; 

) 

buf del ( ) ; 

buf ins(  line ,  n)  ; 

} 


/•  Indicate  that  the  file  has  been  saved.  •/ 

buf saved ( ) 

{ 

b  cflag  z  NO; 

) 


/•  Move  towards  the  head  of  the  file.  •/ 

bufup(  ) 

{ 

/•  The  call  to  buf_gobk()  instead  of  bufgoO 
•  is  made  purely  to  increase  speed  slightly. 


if  ( buf attop(  ) )  { 
return  ; 

) 

else  { 

b_l ine--; 
b uf  gobk (  ) ; 

) 

) 


/•  Do  not  erase  the  work  file  on  a  disk  error.  •/ 
b_f atal  z  NO; 


RED  buffer  routines  --  small-C  version 
Part  2  —  line  routines. 


/•  Return  YES  if  buffer  is  near  the  bottom  line  •/ 

buf nrbot(  ) 

{ 

return  (b  line  >z  b  max  line); 

)  -  _  _ 

/•  Put  nlines  lines  from  buffer  starting  with  line  topline  at 
*  position  topy  of  the  screen. 


ine.  tiy,  nlines) 

'^‘•nlines;  */ 


Source:  redll.sc 

Version;  August  7,  1982;  February  26,  1983 

Copyright  (C)  1983  by  Edward  K.  Ream 


Scan  for  the  start  of  the  current  line. 

Return  ‘count  z  the  If  of  characters  in  the  line. 
Return  ^prefix  z  the  9  of  characters  before  the  line. 


•  * .  y; 
x  (  )  ; 

y  z  outgety (  )  ; 

1  z  b_  1  i  n  e  ; 

while  (nlines  >  0)  { 


b_sca n ( poi n te r ,  count,  prefix) 

int  ‘pointer;  /•  Kludge  --  should  be  char  **  •/ 

int  • count; 

int  *prefix; 

{ 

char  • cp ; 

int  i,  limit,  countl; 
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/•  The  last  line  is  always  null.  */ 
if  ( buf  a  tbot (  ) )  { 

•prefix  =  BUFF_SIZE  -  d_avail  [b_slot]; 
•pointer  =  da t a_a dd r ( b_s 1 o t )  +  •prefix; 

•count  =  0; 
return ; 

} 

/•  Limit  is  the  starting  line  U  of  the  next  block.  •/ 
limit  =  bstart  ♦  d_lines  [b_slot]; 

/•  Point  pointer  at  the  start  of  the  first  line.  •/ 
cp  =  dataaddr  (b_slot); 

/•  Keep  track  of  characters  before  the  line.  •/ 

•prefix  =  0; 

i  =  bstart; 
whi  1 e  — ( 1 )  { 

if  ( i  =  =  limit)  I 

c an t_happen ( " b_sca n  1"); 

) 

/•  Get  length  of  the  line.  •/ 
count  1  =  b_getnum( cp) ; 

if  (  ( count  1  <  0)  |  (“prefix  >=  BUFF_SIZE)  )  { 

cant_happen ( "b_scan  2"); 

} 

/•  At  the  requested  line?  •/ 
if  (i  ==  b_l i ne )  l 
break  ; 

) 

/•  Step  over  the  count  and  the  line.  •/ 
cp  =  cp  +  countl  +  2; 

•prefix  =  “prefix  ♦  countl  +  2; 
i  ♦  ♦  ; 

} 

/•  Point  past  the  line  length.  •/ 
c  p  =  c  p  ♦  2 ; 

/•  Set  values  in  the  calling  routines.  •/ 

•pointer  =  cp; 

•  count  =  countl; 

) 

/• 

Get  and  put  a  2-byte  line  number. 

These  are  machine  independent  substitutes  for  casts: 

•/ 

b_petnum(cp) 
char  • cp  ; 

{ 

/•  simulate:  ip  =  (“int)  cp;  return  “ip;  */ 

return  ('cp  <<  8)  !  *(cp+1); 

} 

b  put  num ( cp ,  num ) 
char  *cp; 
i nt  num ; 

{ 

/*  simulate:  ip  =  (“int)  cp;  “ip  =  num;  •/ 

•cp  =  (num  &  (255  <<  8))  >>  8; 

*(cp+1)  =  num  &  255; 

) 


/•  Delete  the  current  line.  •/ 

buf  del ( ) 

( 

char  *p,  • p 1 ,  *q; 

int  length,  junk; 

i  nt  e  nd  p  ; 

int  back,  current,  next; 

/»  Do  nothing  if  the  buffer  is  empty.  •/ 
if  ( buf a  tbot (  ))  [ 


/»  The  current  block  will  become  dirty.  */ 
is_dirty( b_slot) ; 
b_c  flag  =  YES; 

/• 

Point  p  at  the  line  II  of  the  deleted  line. 
Point  pi  at  the  line  II  of  the  following  line. 
Point  q  passed  the  last  byte  of  the  block. 

*/ 

b  scan(4p,  41ength,  4junk); 

end  p  =  BUFFSIZE  -  d_avail  [b_slot]; 

q  =  data_addr  (bslot)  «■  endp; 

pi  =  p  length; 

P  =  p  -  2; 


/•  Compress  the  block.  •/ 
while  (pi  !=  q)  { 

»p++  r  »p  1  ■*■+  ; 


/•  Adjust  the  avail  and  line  counts  in  the  block.  */ 
d_avail  [b_slot]  =  d_avail  [b_slot]  +  length  +  2; 
d_lines  [b_slot] — ; 

/•  Decrease  the  overall  line  count.  •/ 
b_max_l i ne — ; 

/*  Point  to  the  previous,  current  and  next  blocks.  */ 
back  =  d_back  [b_slot]; 
current  =  d_diskp  [b_slot]; 
next  =  d_next  [b_slot]; 

/•  Move  to  the  correct  block.  */ 

if  (  (next  ==  ERROR)  4  (d_lines  [b_slot]  ==  0)  )  { 

/•  The  last  block  is  empty.  Move  back.  •/ 
if  (back  ! z  ERROR)  { 

swa p_i n( back ,  4b_slot); 
b_s tart  s  b_max_line  - 

d_lines  [b_slot]  +  1; 

} 

} 

else  if  (b_start  ♦  d_lines  [b_slot]  ==  b_line)  { 

/•  The  line  moves  to  the  next  block.  */ 
if  (next  !=  ERROR)  { 

swa p_in(next,  Ab_slot); 
b_start  s  b_line; 

) 

) 


Combine  blocks  if  possible. 

This  is  tricky  code  because  combine()  causes 
side  effects.  Do  not  try  to  pre-compute  the 
arguments  for  the  second  call  to  combine(). 


comb i ne ( d_bac k  [b_slot],  d_diskp  [b_slot]); 
combine(d  diskp  [b  slot],  d  next  [b  slot]); 


/ * - check  code  -- 

check  block( "delete”); 


/•  Delete  n  lines  starting  at  the  current  line.  •/ 

bufdeln(n) 
int  n ; 

{ 


i  =  0; 

whi le (  (i  <  n)  4  (bufatbot()  ==  NO)  )  { 

buf  del ( ) ; 
i  ♦  ♦  ; 

) 


Copy  the  current  line  from  the  buffer  to  line  []. 

The  size  of  line  []  is  linelen. 

Return  k  =  the  length  of  the  line. 

If  k  >  linelen  then  truncate  k  -  linelen  characters. 


buf getln( line ,  linelen) 
char  "line; 

int  1  inelen ; 

{ 

int  count,  i,  junk,  limit; 

char  *  cp ; 

/*  Return  null  line  at  the  bottom  of  the  buffer, 
if  ( buf  a tbot ( ) )  { 

line  [0]  =  CR; 
return  0 ; 


/•  Scan  forward  to  start  of  the  line.  •/ 
b  scan(4cp,  4count,  4junk); 

/*  Copy  line  to  buffer  */ 
limit  =  min( count ,  linelen); 
i  =  0; 

whi le  ( i  <  limit )  { 

line  [i]  =  cp  [  i  ]  ; 
i  ■*■  +  ; 

} 

/•  End  with  zero.  •/ 

line  [min  (count,  linelen  -  1)]  =  EOS; 


( Continued  on  next  page ) 
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(Listing  continued,  text  begins  on  page  34) 

/*  Return  the  number  of  characters  in  the  line.  •/ 
return  count; 


Insert  line  before  the  current  line.  Thus,  the  line 
number  of  the  current  line  does  not  change.  The  line 
ends  with  a  zero  byte  but  not  with  a  CR . 

This  is  fairly  crude  code,  as  it  can  end  up  splitting 
the  current  block  into  up  to  three  blocks.  However, 
the  combinet )  routine  does  an  effective  job  of  keeping 
the  size  of  the  average  block  big  enough. 


bufins(line,  linelen) 
char  line  [j; 
i  nt  linelen; 

{ 

char  *  p  ,  *  q  ; 

int  junk; 

int  lengthl;  /♦  #  of  chars  before  break  point  •/ 

int  length2;  /*  II  of  chars  after  break  point  •/ 

int  i ; 

i f  (  linelen  >  BUFFSIZE)  { 

cant_happen ( "buf i ns  1”); 

) 

/*  Point  p  at  the  start  of  the  current  line.  */ 
b_scan(4p,  Ajunk,  &length1); 

p  r  p  -  2; 

/*  Calculate  0  of  characters  after  break  point.  */ 

1  en  g  t  h  2  =  BUFF_SIZE  -  d_avail  [b_slot]  -  lengthl; 

/•  The  current  slot  is  now  dirty.  */ 
i s_d i r  t y ( b_s  lo t )  ; 

/*  Allow  for  2-byte  line  length.  */ 
if  (lengthl  +  linelen  +  2  >  BUFF_SIZE)  { 


split  block (  length  1 ,  length2,  YES); 
lengtKl  =  0; 

1  ength2  =  BUFF_SIZE  -  d_avail  [b_slot]; 

} 

/• 

At  this  point  we  know  that  the  new  line  will 
fit  on  the  current  block  at  position  lengthl. 


if  (linelen  +  2  >  d_avail  [b_slot])  { 

spl it_blocM length  1 ,  length2,  NO); 

/*  Copy  line  to  the  end  of  the  old  block.  */ 
p  r  data_addr  (b_slot)  ♦  lengthl; 

i  x  0; 

while  (i  <  linelen)  { 

p  [2  ♦  i]  =  line  [  i ] ; 
i  ♦  ♦ ; 

} 

/*  Insert  line  length.  */ 
b_putnum(’p,  linelen); 

/*  Adjust  header.  */ 

d_a va i 1 [ b_s lo t ]  x  d_a va i 1 [ b_s lo t ] - 1 ine 1 en-2 ; 
d_lines[ b_slot] ++  ; 

) 

else  { 

/*  Make  a  hole  in  the  block.  */ 
p  =  data_addr  (b_slot)  ♦  lengthl; 
q  s  p  +  linelen  ♦  2; 

i  =  length2  -  1; 
while  (i  >x  0)  { 

q  [i]  =  P  t i 3  ; 


/•  Put  the  line  length  in  the  hole.  •/ 
b_putnum(p,  linelen); 

/f  Copy  the  new  line  into  the  hole.  */ 
P  =  P  ♦  2; 
i  x  o; 

while  (i  <  linelen)  ( 
p  [i]  s  line  [ i ] ; 
i  +  +  ; 

} 

/*  Adjust  the  header.  */ 

d_a va i 1 [ b_s lo t ]  =  d_a va i 1 [ b_s lot ]- 1 i n e 1 en-2 ; 

d_lines[ b_slot]++  ; 


/• 

Special  case:  inserting  a  null  line  at  the 
end  of  the  file  is  not  a  significant  change. 

•/ 

if  (  (linelen  !=  0)  !  (bufnrbotC)  ==  0)  )  { 

b_c  f 1  a  g  =  YES; 

•  ) 

/*  Bump  the  number  of  the  last  line.  */ 
b_max_l i ne++ ; 

/* - check  code - * / 

check_block( "bufins") ; 


Combine  two  blocks  into  one  if  possible. 
Make  the  new  block  the  current  fflock. 


combine( diskp 1 ,  diskp2) 
int  diskpl,  diskp2; 

{ 

char  * p 1 ,  * p2 ; 

int  slotl,  slot2,  slot3 ; 

int  1 en 1 ,  1 en2 ; 

int  i ; 

/•  Make  sure  the  call  makes  sense.  */ 
if  (  (diskpl  xx  ERROR)  !  (diskp2  ==  ERROR)  )  { 
return  ; 

) 

/•  Get  the  two  blocks.  */ 
s wa p_i n ( d i s kp 1 ,  islotl); 
swap_in( diskp2,  4slot2); 

if  (  (d_next  [slotl]  !=  diskp2)  | 

(d_back  [slot2]  !=  diskpl) 

)  ( 

canthappen ( "combine  1"); 

) 

/*  Do  nothing  if  the  blocks  are  too  large.  */ 
lenl  s  BUFFSIZE  -  davail  [slotl]; 

1 en  2  =  B  UFF_S I Z  E  -  d_avail  [slot?]; 

if  (  (lenl  >  BUFF_SIZE)  |  (len2  >  BUFF_SIZE)  )  { 
cant_happen( "combine  2"); 

) 

if  (lenl  ♦  le n 2  >  BUFF  SIZE)  [ 
return  ; 

) 

/•  Copy  buffer  2  to  end  of  buffer  1.  */ 
pi  x  data_addr  (slotl)  +  lenl; 
p2  x  data_addr  (slot2); 

i  x  0; 

while  (i  <  le  n2 )  [ 

pi  [i]  =  p2  [i]  ; 

; 


1 

/•  Both  blocks  are  now  dirty.  */ 
i s_d ir  ty ( slotl); 
i s_dir ty( s lot2) ; 

/*  Adjust  the  back  pointer  of  the  next  block.  •  / 
if  (d  next  [slot2]  !x  ERROR)  { 

swap_i n ( d_nex t  [slot2],  4slot3); 
d_back  [slot3l  =  ddiskp  [slotl]; 
is_dirty( slot3) ; 

) 

/f 

Adjust  the  current  block  if  needed. 

The  value  of  b_start  must  be  decremented 
by  the  OLD  value  of  d_lines  [slotl]. 

•/ 

if  (bslot  xx  slot2)  { 

b_s lot  x  slotl; 

bstart  x  bstart  -  d_] ines  [slotl]; 

) 

/*  Adjust  the  header  for  block  1.  */ 

d_lines  [slotl]  x  d_lines  [slotl]  +  d_lines  [slot2]; 
d_avail  [slotl]  x  BUFF_SIZE  -  lenl  -  len2; 
d~next  [slotl]  x  d_next  [slot2]; 

/•  Adjust  the  pointers  to  the  last  block.  */ 
if  ( di skp2  ==  btail)  { 
btai 1  x  diskpl; 

} 

/ f  Slot  2  must  remain  in  core  until  this  point.  */ 
f ree  block( slot2) ; 
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/  * - check  code - 

check  bloek( "combine"); 


while  (i  <  length2)  { 
q  [  i]  =  P  [ n ; 


/*  Put  the  block  in  the  slot  on  the  free  list.  */ 

freeblock(slot) 
i  nt  slot ; 

{ 

/*  Link  the  block  into  the  free  list.  */ 
d_next  [slot]  =  b_free; 
b_free  s  d_diskp  [slot]; 

/*  Erase  the  block.  */ 
d_l ines  [slot]  =  0; 
d_avai 1  [slot]  =  BUFF_SIZE; 
is  dirty(slot); 


Create  a  new  block  linked  after  the  current  block. 
Return  the  slot  number  and  a  pointer  to  the  new  block. 


/*  Adjust  the  headers.  * / 

d_lineo  [slot2]  =  d_lines  [b_slot]  —  (b  line-b  start); 
d_avjil  [slot2]  =  BUFF_SIZE  -  length2; 
d_ 1 i n es  [b_slot]  r  b_line  -  b_start; 
d_a v a i 1  ;b_slot]  =  BUFF_SIZE  -  lengthl;; 

/*  Ac  j  us  t  the  pointer  to  the  last  block.  «/ 
if  (a_diskp  [b_slot]  ==  b  tail)  { 
b_tail  =  d_diskp  Tslot2]; 


if  (flag  ==  YES)  { 

/*  Make  the  new  block  the  current  block. 
b_s  ta  r  t  =  b_s  ta  r  t  ♦  d_lines  [b_slot]; 
b  slot  =  slot2; 


/•  int  *f 

new  block  (slotp) 

int  *  slotp  ; 


RED  buffer  routines  --  small-C  version 
Part  3  —  file  routines. 

Source :  red  1 2 . sc 

Version:  August  29,  1982;  February  27,  1983 
Copyright  (C)  1983  by  Edward  K.  Ream 


/*  Get  a  free  disk  sector, 
if  (b  free  !=  ERROR)  { 


/*  Take  the  first  block  on  the  free  list.  •/ 
diskp  =  b  free; 


/*  Put  the  block  in  a  free  slot.  * / 
swa pi n ( d i skp ,  Aslotl); 


/*  Adjust  the  head  of  the  free  list.  */ 
bfree  =  dnext  [slotl]; 


/*  Get  a  free  slot.  */ 
diskp  =  ♦+b_max_diskp ; 
swap_new( diskp ,  Aslotl); 


/•  Return  the  address  of  the  data  area  for  the  slot. 


/*  char  *  */ 
d  at a_add  r (slot) 
int  slot ; 

{ 

return  d_data  ♦  (slot  *  DATA  SIZE) 

} 


HEADER  SIZE; 


/*  Open  the  data  file.  »/ 

/•  int  »/ 
data_open ( ) 

{ 

int  fd; 


/*  Link  the  new  block  after  the  current  block. 
d_next  [slotl]  =  d_next  [b_slot]; 
d_back  [slotl]  =  d_diskp  [b_slot]; 
d_next  [b_slot]  =  diskp; 
if  (d_next  [slotl]  !=  ERROR)  { 

swa p_i n ( d_nex t  [slotl],  &slot2); 
d_back  [slot2]  =  diskp; 
i s_d irty(slot2)  ; 

) 

/*  The  block  is  empty.  */ 
d_lines  [ s  lot  1  ]  =  0; 
d_a vai 1  [slotl]  =  BUFF_SIZE; 
is  dirty ( slot  1 ) ; 


/*  Erase  the  data  file  if  it  exists.  */ 
sysunlink( D  AT  A_F ILE ) ; 

/*  Create  the  data  file.  */ 
b_data_f d  s  syscreat( D ATA_F ILE); 
if  ( b_data_f d  ==  ERROR)  { 

d  isk_error ( "can  not  open  swap  file."); 

1 

/*  Close  the  file,  reopen  it  for  read/write  access. 

sysclose( b_data_fd ) ; 

b_data_f  d  =  s  ysopen ( D  ATA_F ILE ,  2); 

return  b  data  f d ; 


/*  Set  the  user's  field, 
■slotp  =  slotl; 


Split  the  current  block  in  two  pieces.  . 

Lengthl  is  the  number  of  chars  before  the  break  point. 
Length2  is  the  number  of  chars  after  the  break  point. 
If  flag  ==  YES,  make  the  new  block  the  current  block. 


split_block( length  1 .  Iength2,  flag) 
int  lengthl,  length2,  flag; 

i 

char  *p.*q; 

int  slot2 ; 

int  i  ; 


/*  Create  a  new  block, 
new  b lo ck ( A s 1 o t 2 ) ; 


/*  Make  the  slot  the  MOST  recently  used  slot.  */ 

do_lru(slot) 
int  slot ; 

{ 

int  i  ,  lru ; 


Change  the  relative  ordering  of  all  slots 
which  have  changed  more  recently  than  slot. 

•/ 

lru  =  d_lru  [slot]; 
i  =  0; 

while  (i  <  N  SLOTS )  ( 

if  (d_lru  [i]  <  lru)  { 
d_lru  [  i  ] +♦ ; 

} 

; 

} 


/*  Mark  both  blocks  as  dirty.  •/ 

i s_  d i r  t  y ( b_s lot); 
is_dirty( slot2) ; 

/•  Copy  end  of  the  old  block  to  start  of  the  new. 
p  =  data  addr  (b_slot)  *  lengthl; 
q  =  data  addr  ( s 1 o 1 2 ) ; 


/*  The  slot  is  the  most  recently  used.  »/ 
d_lru  [slot]  =  0; 


(Continued  on  next  page) 
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RED  -  Listing 

(Listing  continued,  text  begins  on  page  34) 

Print  an  error  message  and  abort. 

It  would  be  unwise  to  try  to  recover  from  here 
because  the  state  of  the  work  file  is  unknown. 
However,  the  work  file  is  left  intact  so  that  it 
may  be  examined  and  the  original  file  reconstituted. 

*  / 

disk_error (message) 
char  “message ; 

{ 

er  ror ( message  )  ; 

/*  Erase  the  buffer  for  fatal  errors.  */ 
if  ( b_f at  a  1  ==  YES)  { 
buf new(  )  ; 

} 

/*  Jump  to  the  error  recovery  point.  */ 

1  on g j m p ( D_E R R 0 R ,  ERROR); 


/*  Indicate  that  a  slot  must  be  saved  on  the  disk.  */ 

i s_d irty( slot) 
i nt  slot ; 

d  status  [slot]  s  DIRTY; 

) 


*  Put  out  the  block-sized  buffer  to  the  disk  sector.  */ 

put_block ( buf f er ,  sector) 
char  *  buf  fer ; 
i nt  sector  ; 

int  s  ; 

/*  Seek  to  the  correct  sector  of  the  data  file.  */ 
s  =  s ys see k ( b_da t a_f d ,  sector); 

if  ( s  =  =  -1  )  T 

disk_error( "seek  failed  in  put_block . " ) ; 

1 

/*  Write  the  block  to  the  data  file.  */ 
if  ( syswr i te (  b_data_fd,  buffer,  READ_SIZE) 

I  =  R  EA  D_S IZ  E  )  { 

disk_error("write  failed  in  put_block . " ) ; 

} 


Fill  in  the  header  fields  of  the  output  buffer  and 
write  it  to  the  disk. 

*/ 

/*■  char  *  */ 
put_buf ( n) 

Int  n ; 

{ 

int  •  p ; 

if  (n  =  =  0)  { 

cantjiappen ( "put  buf  1”); 

1 

/• 

Fill  in  the  back  and  next  links  immediately. 
This  can  be  done  because  we  are  not  waiting 
for  the  LRU  algorithm  to  allocated  disk  blocks 
The  last  block  that  put_buf()  writes  will  have 
an  incorrect  next  link.  Read_file()  will  make 
the  correction  . 

The  d  avail  field  calculation  allows  for  the 


*  / 

line  length 

in  the 

line  just 

built. 

p  = 

b_buf f  ; 

=  b_max  diskp 

-  1  ; 

/* 

d 

back 

field 

•/ 

»p-»  + 

=  b  max  diskp 

♦  i ; 

/  * 

d 

next 

field 

•/ 

*p+  + 

=  B  UFF_S I Z  E  - 

n  ; 

/• 

d 

avail 

field 

•/ 

*p.*.+ 

=  b_line  -  b 

start; 

/* 

d 

lines 

field 

•/ 

/*  Update  block  and  line  counts.  *  / 
b_max_diskp++ ; 
b_s  ta  rt  =  b_line; 

/*  Write  the  block.  */ 

put_b lock ( b_buf f ,  bmaxdiskp  -  1); 

) 


Write  out  the  slot  to  the  data  file. 


/*  int  */ 
put_s lot( slot) 
int  slot ; 
l 

int  *  p ; 

if  ( d_diskp  [slot]  ==  ERROR)  { 

can t_ happen ("put_ slot"  )  ; 

) 

/•  Copy  header  information  back  to  the  block.  */ 
p  =  d_data  ♦  (slot  *  DATASIZE); 

*p++  =  d_back  [slot]; 

*p*+  =  d_next  [slot]; 

•p+«-  s  d  avail  [slot]; 

*p+  +  =  d_ lines  [slot]; 

/*  Write  the  block  to  the  disk.  *  / 

put_block(d_data  ♦  (slot  *  D AT A_S I Z E ) ,  d  diskp  [slot]); 

} 

/*  Read  a  file  into  the  buffer.  */ 

buf_r_file( file_name) 
char  f i 1 e_name  [  ]  ; 

{ 


i  nt 

i .  j; 

c  ha  r 

• outbuf  ; 

/• 

the  output  buffer 

*/ 

i  nt 

i  n ; 

/» 

input  buffer  index 

*/ 

i  nt 

o  ut ; 

/» 

output  buffer  index 

*/ 

int 

out  save  ; 

/» 

li ne  starts  here 

*  / 

i  nt 

count ; 

/« 

chars  in  line 

*  / 

i  nt 

c ; 

/• 

current  char 

*  / 

int 

•ip; 

/* 

integer  pointer 

*  / 

/•  Clear  the  swapping  buffers  and  the  files.  */ 
buf newt ) ; 

d_status  [b_slot]  =  FREE; 


/*  Open  the  user  file  for  reading  only.  •/ 
b_user_fd  =  sysopen ( f i 1 e_name ,  0); 
if  (b_user_fd  =  r  ERROR)  [ 

d i sk_error ( " f i le  not  found"); 

) 

/*  Open  the  data  file.  •/ 
d  at  a_ope  n ( ) ; 

/*  Erase  the  buffer  on  a  disk  error.  */ 
t_fatal  =  YES; 

/*  The  file  starts  with  line  1.  */ 
b_line  =  1; 

b_s tart  s  1 ; 

/*  There  are  no  blocks  in  the  file  yet.  */ 
b_head  =  b_tail  =  ERROR; 
b_max_diskp  =  0; 

in  =  DATA_SIZE;  /*  Force  an  initial  read.  */ 

out  s  2; 

out  save  =  0; 

b_ lTn  e  =  bstart  =  1; 

outbuf  r  b_buf  f  ♦  HEADERSIZE; 

count  =  0; 

while  (1)  { 

if  ((out  >=  BUFF_SIZE)  &  (out  save  =  =  0))  I 

/*  The  line  is  too  long.  */ 
error  ("line  split"); 

/•  End  the  line.  »/ 
b_putnum( outbuf ,  count); 
b_l ine++ ; 
count  =  0; 

/*  Clear  the  output  buffer.  •/ 
put  buf ( out )  ; 
out  =  2; 
outsave  =  0; 

) 

else  if  (out  >=  BUFFSIZE)  { 

/*  Write  out  the  buffer.  */ 
put_buf( outsave) ; 

/*  Move  the  remainder  to  the  front.  •/ 

i  =  2 ; 

j  =  out  save  +  2; 

while  ( j  <  out )  { 

outbuf  [i++]  =  outbuf  [j++]; 

/*  Reset  restart  point.  */ 
count  =  out  -  out_save  -  2; 
out  save  r  0; 
out  =  count  ♦  2; 

) 

c  s  readl ( Ain) ; 
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iT  (c  ==  CPMEOF)  ( 

i f  ( count  ! =  0 )  { 

/*  Finish  the  last  line.  */ 
b_putnum( outbuf  +  out_save,  count); 
b_line++ ; 
outsave  =  out; 

1 

if  (outsave  !=  0)  { 

put_buf(out_save) ; 

) 

break; 

} 

else  if  (c  ==  LF)  { 

/*  Ignore  LF's  *  / 
continue ; 

} 

else  if  (c  =  =  CR)  { 

/*  Finish  the  line.  •/ 

b_putnum( outbuf  ♦  out_save,  count); 

/*  Set  restart  point.  */ 

b_ 1 i ne  +  +  ; 

ou t_sa v e  =  out ; 

out  =  out  ♦  2; 

count  =  0; 

} 

else  | 

/*  Copy  normal  character.  */ 
outbuf  [out++]  =  c; 
count++ ; 

) 

) 

/•  Close  the  user'  file.  •/ 
syscl osc ( b_u  se  r_f  d ) ; 

/•  Special  case:  null  file  */ 
if  (b_max_diskp  ==  0)  { 

buf  new ( ) ; 
return ; 

} 

/•  Rewrite  the  last  block  with  correct  next  field.  *  / 
ip  =  b_buf  f ; 
i  p+  ♦  ; 

•ip  =  ERROR; 

put_block( b_buf f ,  b_max_diskp  -  1); 

/•  Set  the  pointers  to  the  first  and  last  blocks.  •/ 

bmax  _d i skp-- ; 

b_head  =  0; 

btail  =  b_max_diskp; 

/•  Move  to  the  start  of  the  file.  */ 
b_max_line  =  b_line  -  1; 
b_l i n  e  =  1 ; 

b_s  tart  =  1  ; 

s wa p_i n ( b_head ,  4b_slot); 
b_fatal  =  NO; 


/*  Get  one  character  from  the  input  file.  */ 

ro^dl (in' 
i  n  t  •  i  n  ; 

char  *  i  uf ; 

i  nt  s  ; 

/*  Put  the  input  buffer  in  the  first  slot.  */ 
inbuf  =  d  _  d  a  t  a  ; 

if  ( • i n  ==  DAT  A_S IZ  E )  { 

/•  Read  the  next  sector.  •/ 
s  r  sysread  (b_user_fd,  inbuf); 
if  ( s  =  =  ERROR )  { 

d isk_e rror ( "read  failed"); 

) 

/•  Force  a  CPM  end  of  file  mark.  •/ 
if  (s  <  READ_SIZE)  { 

inbuf  [s  •  C  PM_S I Z  E ]  =  CPMEOF; 

} 

•in  =  0 ; 

) 

/•  Return  the  next  character  of  the  buffer.  •/ 
return  inbuf  [  (  *  i  n  )  +  +  ]  ; 


Put  the  block  from  the  disk  into  a  slot  in  memory. 
Return  the  slot  number  and  a  pointer  to  the  block. 

•/ 


/•  int  «/ 

swap_in( diskp ,  slotp) 
int  diskp; 
int  *  slotp ; 

l 

int  slot,  s ; 

int  «  p ; 

if  (  (diskp  <  o)  |  (diskp  >  b_max_diskp)  )  { 
cant  happen( "swap  in  I");- 

) 

/•  See  whether  the  block  is  already  in  a  slot.  */ 
s  lo  t  =  0; 

while  (slot  <  N  SLOTS )  { 

if  (  ( d_s  ta  tu  s  [slot]  !=  FREE)  4 
(d  diskp  [slot]  ==  diskp) 

)  {  “ 

/•  Reference  the  block.  •/ 
do_lru(slot)  ; 

/•  Set  the  caller's  field.  •/ 

•slotp  =  slot; 
return ; 

} 

slot++ ; 

1 

/•  Clear  a  slot  for  the  block.  •/ 
swap_new( diskp  ,  slotp); 

/•  Seek  to  the  proper  place.  •/ 
s  =  sysseek( b_data_f d ,  diskp); 
if  (s  =  =  -1 )  { 

d i sk_e r r or ( " swa p_i n :  disk  full"); 

} 

/•  Read  the  block  into  the  slot.  •/ 

s  s  sysread ( b_data_fd ,  d_data  ♦  (*slotp  •  DATA_SIZE)); 
if  ( s  =  =  ERROR)  { 

di sk_error ( " swa p_i n :  disk  not  ready"); 

} 

/•  Copy  information  to  arrays  for  easy  access.  »/ 

p  =  d_data  ♦  (*slotp  •  DATA_SIZE); 

d_back  [*slotp]  =  *p++; 

d_next  [*slotp]  =  *p++; 

d_avail  [*slotp]  =  *p++; 

d_lines  [•slotp]  =  •?♦♦; 

/•  Swap  new()  has  already  called  do_lru().  •/ 

} 

/• 

Free  a  slot  for  a  block  located  at  diskp. 

Swap  out  the  least  recently  used  block  if  required. 
Return  slotp . 

•/ 

/»  int  •/ 

swap  new  (diskp,  slotp) 
int  "aiskp; 
int  •slotp; 

{ 

int  slot ; 

/•  Search  for  an  available  slot.  •/ 
slot  =  0; 

while  (slot  <  N  SLOTS )  { 

if  (d_status  [slot]  ==  FREE)  { 
break ; 

} 

slot++ ; 

) 

/•  Swap  out  a  block  if  all  blocks  are  full.  */ 

if  (slot  ==  N SLOTS )  { 

slot  s  swap_out(); 

) 


/•  Make  sure  the  block  will  be  written.  */ 
d_status  [slot]  =  FULL; 
d_diskp  [slot]  =  diskp; 

/•  Reference  the  slot.  •/ 
do_lru( slot)  ; 

/•  Return  slotp.  */ 

•slotp  =  s lot ; 

} 


Swap  out  the  least  recently  used  (LRU)  slot. 
Return  the  index  of  the  slot  that  becomes  free. 

•  / 


/ •  int  * / 
swa  p_out  (  ) 

{ 

int  slot; 


(Continued  on  next  page ) 
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char  c ; 
i  nt  *  i  ; 
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RED  -  Listing 

(Listing  continued,  text  begins  on  page  34) 

/*  Open  the  temp  file  if  it  has  not  been  opened.  * / 
if  ( b_da  ta_f  d  ==  ERROR)  { 

b_data_fd  =  data_open(); 

} 

/*  Find  the  least  recently  used  slot.  */ 
slot  =  0; 

while  (d_lru  [slot]  !=  NSLOTS  -  1)  { 
si ot+* ; 


/*  Do  the  actual  swapping  out  if  memory  is  dirty.  */ 
if  (d_ status  [slot]  ==  DIRTY)  I 
put_s  lot ( slot) ; 
return  slot ; 

i 

/*  d_diskp  is  not  ERROR  if  status  is  not  DIRTY.  */ 
if  ( d_d i s k p  [slot]  ==  ERROR)  { 

cant_happen( "swap_out" ) ; 

] 

/*  Indicate  that  the  slot  is  available.  */ 
d_status  [slot]  =  FREE; 
d_diskp  [slot]  =  ERROR; 

/*  Return  the  slot  number.  */ 
return  slot; 

] 

/*  Write  the  entire  buffer  to  file.  */ 

buf_w  file(file_name) 
char  ¥file_name; 

char  *  da  ta  ; 

int  out,  slot,  lines,  length,  next,  count; 
i  n  t  c  ; 

/*  Open  the  user  file.  Erase  it  if  it  exists.  */ 
b  user  fd  =  s ysc r ea t ( f i 1 e  name); 
iT  (b_user_fd  ==  ERROR)  [ 

disk_error( "create  failed"); 

1 

/*  Copy  each  block  of  the  file.  */ 

out  s  0; 

next  =  b_head; 

while  (next  !=  ERROR)  [ 

/*  Swap  in  the  next  block.  */ 
swap_in(next,  Aslot); 

/*  Get  data  from  the  header  of  the  block.  * / 
next  s  d_next  [slot]; 
lines  =  d_lines  [slot]; 
data  =  data_addr  (slot); 

/*  Copy  each  line  of  the  block.  */ 

count  =  0; 

whi le  ( li nes-- )  { 

/*  Get  length  of  the  line.  •/ 
length  s  b_getnum ( data  +  count); 

/*  Skip  over  length  field.  */ 
count  =  count  ♦  2; 

/*  Copy  each  char  of  the  line.  */ 
whi le  (  length--)  { 

c  =  data  [  count-*-* ] ; 
wri te  1  ( c  ,  Aout) ; 

) 

/*  Add  CR  and  LF  at  end.  */ 
writeKCR,  Aout); 
write1(LF,  4  out); 


*  Force  an  end  of  file  mark.  */ 
wri  teHCPMEOF  ,  4out); 

/*  Flush  the  buffer  and  close  the  file.  */ 
write_f lush( out) ; 
sysclose( b_user_fd) ; 

/*  Kludge:  go  to  line  1  for  a  reference  point.  */ 
s wa p_i n ( b_head ,  4b_slot); 
b_line  =  b_start  =  1; 


Write  one  character  to  the  user's  file, 
i  is  the  current  position  in  the  file  buffer. 


/ *  int  * / 
w  ip  i  t  e  1  ( e ,  i ) 


Source  :  red  1 3 • sc 

Version;  August  29,  1982;  February  26,  1983 
Copyright  (C)  1983  by  Edward  K.  Ream 


/• 

You  may  omit  this  file  if  you  need  to  save  space. 

Just  delete  the  calls  to  check_block(  )  in  the 
file  red12.sc.  Then  delete  the  ^include  red13.sc 
statement  in  file  red. sc. 

•/ 

/• 

The  observer  effect:  None  of  the  routines  of  this  file 
should  ever  call  swap_in()  because  swap_in()  causes 
all  kinds  changes  to  the  data  structures  which  these 
routines  are  trying  to  print  out. 


/• 

Dump  global  varialbes,  all  resident  slots  and 
the  current  block. 

*  / 

buf d ump(  ) 

{ 

dump_var  s(  ) ; 
d  ump_memor  y (  ) ; 
d  ump_block(  ) ; 

1 

can t_nappen( message) 
char  *message ; 

1 

pp( message ) ; 

ppl(":  can't  happen"); 

buf  d  ump( ) ; 
exi t(  )  ; 

} 

/*  Check  the  current  block  for  consistency.  * / 

check_block( message) 
char  *message; 

l 

int  count ,  i ,  total ; 
c  ha  r  *  cp  ; 

if  (  ( b_s lot  ==  ERROR)  ! 

(  b_  1  i  n  e  <  0  )  ! 

(bline  >  bmax  line  ♦  1) 

)  { 

ppl(" check  block  1"); 
cant_happen( message) ; 

} 


if  (  (d_ lines  [b_slot]  <  0) 

(d  lines  [bslot]  >=  BUFF_SIZE)  ! 

(d  avail  [b_slot]  <  0)  ! 

(davail  [b_slot]  >  BUFFSIZE) 

)  ( 

ppl(" check  block  2"); 
cant_happen( message) ; 

} 

/•  Make  sure  there  are  at  least  enough  lines.  */ 
cp  =  data_addr  (b_slot); 
total  =  0; 
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while  (i  +  +  <  d_lines  [b_slot])  { 
count  =  b_getnum ( cp)  ; 
total  =  total  +  count  +  2; 
cp  :  cp  +  count  +  2; 

if  (  (count  <  0)  ! 

(count  >  B  UFF_S IZ  E )  ! 

(total  >  B  UFF_S I Z  E ) 

)  ( 

ppl('' check  block  3"); 
cant  happen( message) ; 


/*  Dump  the  current  block.  */ 

dump_block(  ) 

{ 

int  lines,  c,  count,  i,  j,  total; 
c  ha  r  *  cp ; 

PPl ( ""  ) ; 

ppl("Dump  of  current  block:"); 

P  P 1  (  "  "  ) ; 

lines  =  d_lines  [b_slot]; 
cp  =  data_addr  (b_slot); 
total  =  0; 

i  =  0; 

while  (  (i  <  lines)  4  (total  <=  BUFF_SIZE)  )  { 
count  =  b  getnum( cp)  ; 
total  r  total  ♦  2; 
c  p  =  c  p  ♦  2 ; 

p  p  (  "  1  i  n  e  "  )  ; 

ppdec(i  ♦  1,  3): 
pp(",  count  "); 
ppd  ec ( count,  3); 
pp ( " ,  total  "  ) ; 
ppdec ( total  ,  3  ) ; 

P  P  (  "  :  "  ) ; 


i  f  (  ( count  <  0 ) 
return  ; 

) 


(total  <  0)  )  l 


/*  Print  each  line  of  the  block.  */ 
j  =  0; 

if  (count  >  50 )  { 
ppl ( ""  )  ; 

) 

while  (  (j  <  count)  4  (j  <  80)  )  { 

c  =  cp  [ j ]  4  127; 

if  ( c  =s  TAB)  { 

ppc  (  '  ' )  ; 

) 

else  if  (c  <  32)  { 

ppc ( ' * ' ) ; 

ppc  (  c  +  6*4 )  ; 

) 

else  { 

ppc ( c ) ; 

} 

total** ; 

if  (total  >=  B  UFF_S I Z  E )  { 
break ; 


pp(",  lines  "); 
ppdec ( d_lines  [i],  6); 

P  p  (  "  ,  1  r  u  "  )  ; 

ppdec ( d_lru  [  i  ]  ,  3 )  ; 

pp(",  status  " ); 

ppd ec ( d_s ta tus  [i],  3); 

P  P 1  <  "  "  )  ; 


/*  Dump  all  global  variables.  */ 


dump_vars( ) 

l 


pp( " slot  "  )  ; 
ppdec ( b_slot  ,  3  )  ; 
pp(" ,  maxdiskp  "  ); 
ppdec ( b_max_diskp  ,  3); 
p  p  (  " ,  line  " ) ; 
ppdec(b_line,  5); 
pp(",  maxline  "); 
ppdec ( b_max_line ,  5); 
pp( " ,  start  " ) ; 
ppd ec ( b_s ta r t ,  3); 
pp( " ,  head  " ) ; 
ppdec ( b_head ,  3 ) ; 
p  P ( " ,  tail  " ) ; 
ppdec ( b_tai 1 ,  3 )  ; 
p  p ( " ,  free  " )  ; 
p  pd  ec ( b_f  re  e  ,  3  )  ; 
ppl ( "" ) ; 
pp( "back  "); 

ppdec(d_back  [b_slot],  3); 

pp(  ,  next  ")  ; 

ppdec(d_next  [b_slot],  3): 

pp(",  avail  "); 

ppdec ( d_avai 1  [b_slot],  3); 

pp(",  lines  "); 

ppdec ( d_l ines  [b_slot],  3); 

p  p  (  "  ,  1  r  u  "  )  ; 

ppdec(d_lru  [b_slot],  3); 

pp(",  status  "); 

p pd ec ( d_s ta tu s  [b_slot],  3); 

pp(",  diskp  "); 

ppdec ( d_diskp  [b_slot],  3); 

ppl ("") ; 


/*  Output  a  string  to  the  dump  device  (console).  */ 

pp(  str  ) 
char  *  str; 

{ 

wh  i  1  e  (  *  s  tr  )  { 

syscout( *  s  t  r  +  +  ) ; 

) 

} 

/*  Output  a  string  to  the  dump  device,  followed  by  a  CR/LF. 

ppl ( str  ) 
char  *  str ; 

{ 

pp ( s  tr  )  ; 
s  yscout ( 1 3  )  ; 
syscout (10); 

} 

/*  Print  a  decimal  number  in  a  field  of  width  w.  */ 

ppdec ( numbe  r ,  w) 
i nt  number ; 
int  w ; 

{ 


int  count ,  k ,  zs  ; 
char  c,  buf  f  er [ 1 0  ]  ; 


pp 1 ( " "  )  ; 

cp  =  cp  *  count; 


Dump  all  the  resident  slots. 


dump  memor  y ( ) 

{ 


ppl("Dump  of  slots:"); 
ppl ( "" ) ; 


while  (i  <  N  SLOTS )  ( 


p  p  (  "  s  1  o  t  "  )  ; 

ppdec(i,  2); 

pp(",  diskp  "); 

ppdec ( d_diskp  [i],  6); 

pp(",  back  "); 

ppdec(d_back  til,  6); 

p  p (  "  ,  next  " ) ; 

ppdec ( d_next  til,  6); 

pp(",  avail  "); 

ppd ec ( d_a va i 1  [i],  6); 


count  =  0; 
zs  =  0; 
k  =  10000; 

if  (number  <  0)  { 

number  =  -number; 
buffer  [count*-*-]  = 

} 

while  (k  >=  1)  { 

e  =  number/k  +  'O'; 

if  (  (c  !  =  ’O')  1  (k  ==  1)  !  (zs  ==  M)  { 

z  s  =  1  ; 

buffer  [count**]  =  c; 

} 

number  =  nunberlk ; 
k  =  k  /  1  0  ; 

} 

buffer  [count]  =  0; 
while  (count**  <  w)  { 
syscout ( '  ' ) ; 

} 

pp(  buffer)  ; 


/*  Print  one  character  to  the  dump  device  (console).  */ 


ppe ( c ) 
char  c ; 
{ 


syscout ( c ) ; 


End  Listings 
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Anatomy  of  a  Digital  Vector 
and  Curve  Generator 


Have  you  ever  wondered  how  your 
computer  draws  a  line  on  your  TV 
set?  All  you  tell  the  computer  is 
endpoints  of  the  line,  and  the  CPU  does 
the  rest.  For  example, 

PLOT  0,0  :  DRAWTO  310,159 

will  draw  a  line  from  the  upper  left  corner 
of  the  screen  to  the  lower  right  corner.  To 
fill  in  all  the  points  on  the  line  in  between 
the  endpoints  is  exactly  what  the  DDA 
(Digital  Differential  Analyzer)  algorithm 
does. 

In  this  article,  I  will  try  to  explain 
how  the  Unit  Increment  DDA  vector  gen¬ 
erator  works  —  also  how  Marvin  Minsky’s 
circle  generator  works.  I  have  included 
BASIC  programs  for  both  the  vector  and 
circle  generators.  Both  of  these  curve  (a 
straight  line  is  a  special  case)  generators 
are  incremental,  meaning  that  point  N+l 
is  generated  from  point  N. 

The  DDA  Vector  Generator 

The  DDA  solves  the  differential  equa¬ 
tion  for  a  straight  line  between  given  end¬ 
points.  The  equation  used  by  the  DDA  is 
dy/dx  =  (y,  -  y0)/(x,  -  x0) 

This  says  that  the  slope  of  the  line  is  equal 
to  the  difference  of  the  y  coordinates  of 
the  endpoints  divided  by  the  difference 
of  the  x  coordinates.  Note:  dy  means  a 
very  small  change  in  y  and  dx  means  a 
very  small  change  in  x. 

Given  the  endpoints  (x0,yo)  and 
(xi,yi),  DX=Xi-x0  and  DY=y1-y0.  If 
the  slope  is  less  than  45  degrees,  as  in 
Figure  1  (at  right),  then  ABS  (DY/DX)  is 
less  than  1 .  Let  the  estimate  of  the  line 
length  be  N  =  abs(DX).  Under  the  above 
constraints,  the  routine  (in  pseudocode) 
for  the  incremental  solution  is: 

for  1=0  to  N- 1  do 
begin 

X(I+1)=  1  *sgn(DX)+  X(I) ; 
Y(I+l)=abs(DY/DX)*sgn(DY)+Y(I); 
end; 

for  1=0  to  N  do 
begin 

plot  ( X  ( I )  ,Y ( I )  ); 
end ; 
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When  N,  the  line  length  estimate,  equals 
abs(DX),  and  the  x  increment  is  1,  the 
“for”  statement  will  trace  out  all  the 
points  between  the  endpoints  of  the  line. 

If  the  angle  is  greater  than  45  degrees, 
we  flip  the  places  of  X  and  Y  in  the  above 
routine.  The  BASIC  program  shown  in 
Listing  1  (page  67)  handles  all  cases  of 
endpoint  location. 

It’s  important  to  note  that  abs(DY/ 
DX)  is  always  less  than  or  equal  to  1.  If 
this  constraint  is  violated,  then  the  role  of 
the  x  and  y  coordinates  must  be  reversed, 
and  abs(DY)  is  used  as  the  line  length 
estimate. 


Minsky’s  Circle  Generator 

Figure  2  (page  66)  shows  a  circle 
with  a  set  of  x,y  axes.  We  will  consider 
the  points  (x,0)  and  (0,y),  since  these  two 
points  form  the  basis  of  vectors  that  span 
all  of  two-dimensional  space.  Take  the 
point  (x,0)  and  consider  what  happens 
when  that  point  is  rotated  by  a  very  small 
amount,  a.  This  will  twist  point  (x,0)  into 
(x,a*x).  Now  point  (0,y)  will  be  twisted 
(at  the  same  time)  into  the  point  (a*y,y). 
As  you  can  see,  the  amount  of  twist  is 
proportional  to  the  point’s  distance  from 
the  origin.  This  is  a  way  of  describing 
circular  motion. 


Now  we  form  the  following  matrix 
equation: 

P(n  +  1)  =  p(n)*T(a), 
and 

P(i)=(xi,yi), 

a  point  T (a)  = 
so  we  now  havi 

(x(n+l),y(n+l))  =  (y(n),y(n)) 

This  is  close  to  what  we  want,  but  it  has 
one  problem:  The  determinant  of  matrix 
T  is  not  equal  to  1.  If  det(T)>l,  then 
the  matrix  will  generate  a  spiral  of  in¬ 
creasing  radius.  If  det(T)<l,  then  the 
curve  generated  is  a  decreasing  radial  spi¬ 
ral.  So  only  when  det  ( T )  =  1  does  the 
curve  close  on  itself.  Let’s  try  changing  T 
so  det(T)=  1. 

This  equation  has  all  the  properties  we 
are  looking  for;  a  is  the  angular  velocity 
of  the  transition  of  point  P(n)  into  point 
P(n+1).  a  is  a  small  number  less  than  or 
equal  to  1.  If  a=  1  then  a  closed  curve 
with  six  equally-spaced  points  is  generated. 
The  smaller  a  is,  the  closer  the  points  of 
the  curve  will  be,  and  the  rounder  the  cir- 


Figure  1. 

Digital  Differential  Analyzer  Vector  Generator  (Xi  y^j 


Therefore,  the  x  increment  equals  1  times  SGN(DX),  and  the  y  increment 
equals  iDY/DXl  times  SGN(DY).  Let  N  equal  iDXl.  Note:  N  equals  the 
largest  delta. 
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cle  will  be. 

Now  that  we  have  the  matrix  form  of 
the  circle  generator,  let’s  get  it  into  itera¬ 
tive  form  for  use  by  a  program.  Converting 
the  form  matrix  equation  to  simultaneous 
linear  equations  gives  the  following. 

(1)  x(n+l)  =  x(n)-a*y(n) 

(2)  y(n+l)  =  a*x(n)+(l-a2)  *y(n) 


These  two  equations  let  you  generate  the 
point  (x(n+ l),y(n+ 1)  )  from  the  point 
(x(n),y(n)),  but  this  still  involves  a  good 
deal  of  arithmetic.  You  have  to  square  a 
and  subtract  it  from  1 ,  then  multiply  it 
by  y(n).  To  speed  up  the  circle  generator, 
we  will  solve  equation  1  for  x(n)  and 
substitute  it  into  equation  2.  Performing 
the  arithmetic  yields: 

(1)  x(n+l)  =  x(n)-a*y(n) 

(2)  y(n+l)  =  a*x(n+l)+y(n) 

This  is  what  we  were  after  all  the  time. 
Writing  the  above  in  BASIC,  we  get  the 
following  program : 

10  FOR  1  =  0  TON 
20  X=X-A  * Y 

30  Y= A  *  X  + Y 

40  PLOT  X,Y 

50  NEXT  I 

which  is  the  heart  of  the  program  in  List¬ 
ing  2  (page  67). 

A  closing  comment  about  the  circle 
generator.  If  a  is  of  the  form  l/2n,  the 
multiplication  can  be  replaced  by  a  shift 
operation.  This  makes  the  routine  well- 
suited  fora  hardware  implementation. 
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(Listing  begins  at  right) 


Figure  2. 


Incremental  Circle  Generator 
Y  AXIS 


L..  P„„  -r„T.  T-(J  '£),  Pi  -(*;) 

Note:  For  T  to  generate  a  closed  curve,  DET(T)  must  equal  1,  therefore 
i p  must  equal  (1  -  a2) 


("I )  xn  +  i 

(2)  yn+i 


*n  -  ayn 
axn  +  (1  -  a2  )yn 


Solve  (1)  for  xn:  xn  =  xn  +  i  +  ay 


Substitute  (1)  into  (2):  yn+1  =  a(xn+I  +  ayn)  +  (1  -  a2 )  yn 
So:  yn+i  =  axn+j  +  a2yn  +  yn  -  a2yn  =  axn+1  +  yn 

(1 )  xn+1  =  xn  -  ayn 

(2)  yn+i  =  axn+1  +  yn 


Leads  to  the  following  BASIC  program: 

10  FOR  I  =  0  TO  N 

20  X  =  X  -  A  *  Y 

30  Y  =  A  *  X  +  Y 

40  PLOT  X,Y 

50  NEXT  I 
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Unit  Increment  DDA 

Listing  One 

(Text  begins  on  page  65) 

10  REM  UNIT  INCREMENT  DDA 
15  REM 

20  REM  Setup  display  for  high  res. 
30  REM  320  X  160  pixels, 

40  REM  colors  are  black  and  white 
50  GRAPHICS  8 

60  SETCOLOR  1 , 0 , 1 4 : SETCOLOR  2,0,0 
70  COLOR  1 
8  0  REM 

90  REM  Get  the  two  end  points  for 


100 

REM  the  vector 

to  draw. 

110 

?  "X0,Y0,X1,Y1 

II 

120 

INPUT  X0 , Y0 , XI 

i  Y 1 

130 

REM 

140 

REM  Plot  the  f 

irst  endpo 

i  nt 

150 

PLOT  X0,Y0 

160 

REM  Calculate 

the  deltas 

170 

DX=X1-X0 

180 

DY=Y1-Y0 

190 

SX=SGN ( DX) : REM 

Direction 

of  X  i 

ncr 

200 

SY=SGN(DY) : REM 

Direction 

o  f  Y  i 

ncr 

210 

IF  ABS(DX)  <  ABS(DY)  THEN  GOTO 

350 

220 

REM  ABS(DX)  > 

ABS( DY) 

230 

REM  Increment 

X  axis  by 

1  unit 

240 

REM  Increment 

Y  axis  by 

f  r  ac  t  io 

n 

250 

DYDX=ABS(DY/DX) 

260 

N= ABS ( DX) : REM 

N=Length  e 

stimate 

270 

FOR  CNT= 1  TO  N 

280 

X0=X0+1*SX 

290 

Y0=Y0+DYDX*SY 

300 

PLOT  INT(X0) ,INT(Y0+0.5) 

310 

NEXT  CNT :GOTO 

110 

320 

REM  ABS ( DX)  <= 

ABS ( DY) 

330 

REM  Increment 

Y  axis  by 

1  unit 

343 

REM  Increment 

X  axis  by 

f ractio 

n 

353 

N= ABS ( DY) : REM 

Line  length  est. 

360 

DXDY=ABS ( DX/DY) 

370 

FOR  CNT= 1  TO  N 

380 

Y0=Y0+1*SY 

390 

X0=X0+DXDY*SX 

400 

PLOT  INT( X0+0 . 

5) , INT( Y0) 

4  10 

NEXT  CNT 

420 

GOTO  110 

Incremental  Circle 
Generator 

Listing  Two 

(Listing  continued,  text  begins  on  page  65) 

100  REM  Set  color  to  black  and  white 
110  GRAPHICS  8 

120  SETCOLOR  2 , 0 , 0 : SETCOLOR  1,0,14 
130  COLOR  1 
140  REM 

150  REM  CX,CY  is  the  center  of  the  screen 
160  CX= 16 0 : CY=8 0 
170  REM 

180  REM  The  smaller  alpha  is,  the  more 
190  REM  more  points  that  are  needed 
200  REM  to  close  the  circle. 

210  ?  "INPUT  RADIUS,  ALPHA,  #  OF  POINT" 

220  INPUT  R, A,N 
230  Y=R:X=0 
240  REM 

250  REM  The  following  is  the  main  loop 
260  REM  of  the  circle  generator. 

270  FOR  1=0  TO  N 

280  X=X-A* Y 

290  Y= A* X+ Y 

300  PLOT  X+CX , Y+CY 

310  NEXT  I 

320  STOP 

330  GOTO  210 

End  Listing  Two 


Incremental  Circle 

Generator 

Listing  Two 

10  REM  INCREMENTAL  CIRCLE  GENERATOR 
15  REM 

20  REM  This  routine  will  generate  an 
30  REM  almost  circle  for  alpha  <=  1. 
40  REM  Alpha  is  the  angular  velocity 
50  REM  of  the  points  making  up  the 
60  REM  circle.  The  smaller  alpha  is 
70  REM  the  rounder  the  circle. 

8  0  REM 

90  REM  Set  display  to  320x160  pixels 
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Fast  Matrix  Operations 

in  Forth,  Part  II 


In  Part  I  of  this  series  ( DDJ  No.  80, 
June  1983),  a  matrix-defining  word 
and  some  fundamental  accessories 
were  presented.  In  this  installment,  pro¬ 
grams  for  performing  matrix  operations 
and  some  more-advanced  accessories  are 
presented.  In  order  to  use  the  programs 
shown  in  screens  210  to  227  (pages  73-79), 
the  programs  given  in  Part  I,  i.e.,  screens 
207  to  209,  must  be  preloaded. 

Several  points  from  Part  I  deserve 
reiteration.  These  programs  are  in  Poly- 
forth  for  the  IBM  PC  from  Forth,  Inc. 
An  8087  numeric  coprocessor  must  be 
installed  in  the  IBM  PC.  Since  the  data 
contained  in  the  matrices  reside  outside 
the  Polyforth  dictionary  (beyond  the  first 
64  KB  segment  of  memory),  more  than 
64  KB  of  RAM  is  needed.  Application 
programs  that  will  be  presented  in  Part  III 
will  require  320  KB. 

Regarding  programming  style,  the 
programs  have  been  written  mostly  in 
Polyforth  assembly  language  rather  than 
Polyforth  proper  in  order  to  maximize 
speed.  Typically,  numeric  programs  such 
as  these  run  five  times  faster  in  assembly 
than  in  Polyforth.  Benchmark  times  are 
shown  in  Figure  1  (at  right).  Two  timings 
are  given  for  an  operation,  one  for  10th- 
order  square  matrices  and  another  for 
50th-order  square  matrices.  It  is  interest¬ 
ing  to  compare  these  timings  with  those 
resulting  from  similar  programs  involving 
different  language  and  hardware  combina¬ 
tions.  For  example,  the  matrix  inversion 
program,  INV,  is  1 10  times  faster  than  an 
identical  algorithm  implemented  in  the 
standard  BASIC  for  the  IBM  PC. 

Although  there  was  little  compromise 
in  trading  off  program  compactness  for 
program  speed,  it  should  be  noted  that 
the  entire  set  of  programs,  screens  207  to 
227,  occupies  only  5186  bytes  of  RAM. 
Considering  this  compactness  and  the 
widespread  applicability  of  matrix  opera¬ 
tions,  I  believe  that  it  is  not  unreasonable 
to  suggest  that  a  refinement  of  these 
operations,  perhaps  more  in  the  style  of 
APL,  should  be  made  a  standardized 
superset  of  the  Forth  language.  Unfor¬ 
tunately,  the  Forth  community,  in  general. 
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seems  to  have  only  a  casual  interest  in 
floating-point  applications.  A  “fixed-point 
philosophy”  has  been  widely  promoted 
and  justified  in  terms  of  a  speed  superi¬ 
ority  of  integer  arithmetic  over  floating¬ 
point  arithmetic.  With  an  8087-equipped 
computer,  this  rationale  simply  does  not 
apply.  Most  of  the  64-bit  floating-point 
operations  such  as  F*  and  FSWAP  are 
actually  faster  than  their  16 -bit  integer 
counterparts.  If  numeric  coprocessors 
similar  to  the  8087  become  common  in 
future  microcomputers,  a  fixed-point 
philosophy  would  be  totally  unjustified 
for  Forth. 

Program  descriptions  follow.  In  the 
usage  examples,  it  is  assumed  that  matrices 
X,  Y,  and  Z  have  been  defined  and  are  of 
suitable  dimensions.  Algebraic  equivalents 
to  the  usage  examples  are  given  in  terms 
of  Xi,  X2,  Yj ,  Y2,  Zi,  and  Z2,  where  the 
subscripts  refer  to  the  first  and  second  of 
two  interlaced  submatrices  comprising 
each  matrix. 

AA,  AA!,  AA@  —  These  are,  respec¬ 
tively,  surrogate  matrix,  surrogate  matrix 
store,  and  surrogate  matrix  fetch.  After 
initialization  by  either  of  the  two  phrases, 

’  X  adr! 


’  X  dim@ 

AA  becomes  the  functional  equivalent  of 
X,  AA!  becomes  the  functional  equiva¬ 
lent  of  X  !1,  and  AA@  becomes  the 
functional  equivalent  of  X  @1. 

A!,  R!,  C!  —  Respectively,  matrix  store, 
row  store,  and  column  store.  Following 
execution,  input  into  the  matrix  is 
prompted.  Usage  examples: 

’  X  A! 

’  X  3  R! 

’  X  5  C! 

A.,  R.,  C.  —  Display,  respectively,  a  ma¬ 
trix,  a  matrix  row,  and  a  matrix  column. 
Usage  examples: 

’  X  A. 

’  X  2  R. 

’  X  7  C. 

A1 !,  R1 !,  Cl!,  Al.,  Rl.,  Cl.  -  Simi¬ 
lar  to  the  preceding  except  that  they 
apply  only  to  the  first  of  two  interlaced 
matrices. 

a-!  —  Stores  the  number  on  the  numeric 
stack  into  every  element  of  a  matrix. 
Usage  example: 

3.14  ’  X  a-! 

excAl,  excRl,  excCl  —  Exchange,  re¬ 
spectively,  matrices,  matrix  rows,  and 


Time,  Seconds 


Operation 

Comment 

lOx  10  Matrices 

50x50  Matrices 

a-! 

0.010 

0.072 

excAl 

exchange 

0.022 

0.218 

-> 

transfer 

0.026 

0.121 

excl2 

0.015 

0.197 

TRNSP 

transposition 

0.017 

0.113 

a* 

scalar  mult. 

0.014 

0.192 

A+ 

addition 

0.020 

0.191 

A* 

multiplication 

0.099 

9.822 

"p* 

0.100 

9.825 

INV 

inversion 

0.217 

22.179 

DET 

determinant 

0.074 

4.969 

sortA  1 

sort 

0.106 

5.824 

sortA 

double  sort 

0.139 

7.908 

polyA  1 

0.013 

0.151 

rndA 

random  no.  fill 

0.032 

0.612 

Figure  1. 

Polyforth  Matrix  Operation  Benchmarks 
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matrix  columns.  Usage  examples: 
’  X  ’  Y  excAl 
’  X  ’  Y  5  lOexcRl 
’  X  ’  Y  4  4  excCl 


polyVl  —  Enters  the  elements  of  a  poly¬ 
nomial  into  a  column  vector,  i.e.,  an 
m-by-1  matrix.  Usage  example: 

3.0  ’  X  poly VI 


— >  —  Matrix  transfer.  Usage  example: 

’  X  ’  Y  1  2  -> 

In  algebraic  notation,  Y2  =  Xi . 

exc!2  —  Exchanges  interlaced  matrices. 
Usage  example: 

’  X  excl2 

TRNSP  —  Matrix  transposition.  Usage 
example: 

’  X  ’  Y  TRNSP 

T 

In  algebraic  notation,  Y!  =  X( . 

a*  —  Multiplies  every  element  of  a  ma¬ 
trix  by  the  number  on  the  numeric  stack. 
Usage  example: 

12.34  ’  X  a* 

A+  —  Adds  two  matrices.  Usage  example: 
’  X  ’  Y  A+ 

In  algebraic  notation,  Y]  =  Y2  +  X!. 

A*  —  Multiplies  two  matrices.  Usage 
example: 

’  X  ’  Y  ’  Z  A* 

In  algebraic  notation,  Z[  =  X]  Yi . 

T*  —  Transposes  a  matrix  and  then  mul¬ 
tiplies  it  by  a  second  matrix.  Usage  exam¬ 
ple: 

,  x  ,  Y  ,  z  T* 

In  algebraic  notation,  Zj  =  X]T  Y2 . 

INV  —  Inverts  a  matrix.  Usage  example: 

’  X  INV 

In  algebraic  notation,  X!  =  Xj1 

DET  —  Finds  the  determinant  of  a  matrix 
and  puts  the  result  on  the  numeric  stack. 
Usage  example: 

’  X  DET 

sortA,  sortAl  —  Sorts  the  elements  of  a 
matrix  in  ascending  order.  Usage  example: 

’  X  sortA 

The  sorting  is  performed  as  indicated  by 
the  following  arrows: 


sortAl  sorts  X]  only,  whereas  sortA  sorts 
both  X!  and  X2  with  respect  to  the  values 
in  X] . 

polvRl  •  Enters  the  elements  of  a  poly¬ 
nomial  into  a  matrix  row.  Usage  example: 

2.0  ’  X  5  poly R 1 

Here,  the  following  values  will  be  entered 
in  row  5  of  the  matrix  as  indicated: 


X  = 


2  4  8  16  .  .  . 


polyAl  —  Starting  with  a  matrix,  e.g., 
X,  such  that 


X  = 


Xl 

X2 

X3 

X4 


The  phrase 


’  X  polyAl 


results  in 


1 

Xl 

Xl2 

xi3 

1 

x2 

X22 

Xj3 

X  = 

1 

x3 

x32 

X33 

1 

x4 

x42 

X43 

V*  —  Multiplies  two  column  vectors, 
i.e.,  mxl  matrices.  Usage  example: 

’  X  ’  Y  V* 

The  result  is  placed  on  the  numeric  stack. 

rndA  —  Fills  a  matrix  with  uniformly 
distributed  pseudo-random  numbers.  Us¬ 
age  example: 

’  X  rndA 

In  addition  to  the  above  matrix  oper¬ 
ations,  a  few  fundamental  scalar  opera¬ 
tions  missing  from  my  version  of  Poly- 
forth  have  been  included.  [We  understand 
that  the  most  recent  release  of  Poly  forth 
now  includes  a  complete  trig  package. 
—  Ed.]  They  are: 

SIN  —  Sine  function  (angle  must  be  in 
radians) 

COS— Cosine  function  (angle  must  be 
in  radians) 

RND  —  Places  a  uniformly  distributed 
pseudo-random  number  between  0  and  1 
on  numeric  stack 

RANDOMIZE  —  Reseeds  random  number 
generator 

This  concludes  Part  II  of  a  three-part 
series.  In  Part  III,  the  operations  presented 
in  the  first  two  parts  will  be  used  to  build 
some  application  programs. 


( Listing  begins  at  right) 
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210  LIST 

O  One  Dimensional  Arrays  and  Random  Number  Generator  ) 

1  SOAR I ABLE  a a  SVARIABLt  cc  SVARIABLE  mm  LVARIABLE  xx 

2  24293.0  aa  S!  99991.0  cc  S!  199017.0  mm  S!  12345.0  xx  L? 

3  ASSEMBLER  CREATE 

4  (END)  FLBt  R32  aa  FLD  R64  xx  FMUL  R32  cc  FADD  R32  mm  FDIV 

5  REV  FPREM  1  N5  FSTP  0  N)  FLD  R32  mm  FMUL  R64  xx  FSTP  RET 

6  CODE  RND  (RND)  CALL  NEXT 

7  ;  RANDOMIZE  .  "  Seed  =  "  IN#  xx  L!  ; 

8  5  ARRAY  CREATE  1+  2*  ALLOT  ; CODE  0  POP  O  SHL  W  0  ADD 

9  0  INC  O  INC  O  PUSH  NEXT 

10  :  T.  COUNTER  SWAP  -  >N  1000.0  F/  3  F.  . “  sec."; 

11  :  START  COUNTER  ; 

12  CODE  (rndA)  m  L.DA  n  MUL  O  1  MOV  adr  LDA  65520  #  W  MOV 

13  BEGIN  (RND)  CALL  0  DO  LSG  R64  W  )  FSTP 

14  2  2  SUB  2  DS  LSG  0  INC  LOOP  NEXT 

15  '  rndA  dim3  n!  m!  (rndA)  ; 


211  LIST 

O  (  SIN  and  COS  ) 

1  LVARIABLE  SI  .9999999999999999  SI  L! 

2  CODE  COS  FLD1  FLOP  I  FSCALE  1  N)  FSTP  1  FXCH  FPREM  1  N>  FSTP 

3  FABS  FLD1  FCHS  FLDPI  2  N)  FSUB  -POP  FSCALE  1  N)  FSTP  1  FXCH 

4  FABS  1  N)  FSUB  REV  R&4  SI  FMUL  FPTAN  i  N)  FLD  0  N)  FMUL  NO 

5  1  FXCH  O  N)  FMUL  NO  1  N)  FADD  FSQRT  1  N>  FDIV  NEXT 

6  CODE  SIN  FLD1  FCHS  FLDPI  FSCALE  1  N)  FSTP  1  N)  FSUB 

7  FLD 1  FLDPI  FSCALE  1  N)  FSTP  1  FXCH  FPREM  1  N>  FSTP 

8  FABS  FLD1  FCHS  FLDPI  2  N)  FSUB  -POP  FSCALE  1  N>  FSTP  1  FXCH 

■7  PASS  1  N)  FSUB  REV  R64  SI  FMUL  FPTAN  1  N)  FLD  O  N)  FMUL  NO 

10  1  FXCH  O  N)  FMUL  NO  1  N)  FADD  FSQRT  1  N)  FDIV  NEXT 

1 1 
1  2 

13 

14 

1 5 


O  (  Surrogate  Matrix  Fetch  and  Store,  Initialized  by  dim®  > 

1  CODE  AA!  O  POP  m  MUL  2  POP  O  2  ADD  adr  LDA  O  2  ADD  1  DS  SSG 

2  2  DS  LSG  R64  65520  FSTP  i  DS  LSG  NEXT 

3  CODE  A  A3  0  POP  m  MUL  2  POP  O  2  AE>D  adr  LDA  O  2  ADD  1  DS  SSG 

4  2  DS  LSG  R64  65520  FLD  1  DS  LSG  NEXT 

5  CODE  AA  O  POP  m  MUL  2  POP  O  2  ADD  adr  LDA  O  2  ADD  2  PUSH  NEXT 


(Continued  on  next  page) 
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10 
1  1 
1  2 
1  3 

1  4 

i  5 


0  (  Interlaced  Matrix  and  Row  and  Column  Input  and  Output  ) 

1  ;  C!  jl  a)  a 3  dim®  DROP  m!  m3  0  DO  CR  .  "  a (  "  I  .  .  "  ,  " 

2  j  3  .  .  "  )  =  "  I m  . "  i  "  I N#  I  j  3  AA  !  !  LOOP  ; 

3  :  C .  j !  a!  a3  dim®  DROP  m 1  m3  O  DO  CR  a(  "  I  .  .  "  ,  " 

4  j3  "  I  j3  AA  33  FSWAP  N.  .  "  i  "  N.  LOOP  ; 

5  :  R!  i  '  a'  a3  dim®  n!  DROP  n3  O  DO  CR  .  "  a (  "  i  3  .  .  "  ,  " 

6  I  .  IN#  .  "  i  "  IN#  iS  I  AA  ! !  LOOP  ; 

7s  R.  if  a!  a3  dim®  nl  DROP  n3  O  DO  CR  . "  a (  "  i 3  .  . "  ,  “ 

8  I  i8  I  AA  33  FSWAP  N.  . "  i"  N.  LOOP  ; 

9  :  A.  a!  a3  dim3  DROP  m!  m3  O  DO  CR  .  “  Row  "  I  .  a3  I  R.  LOOP  ; 

10  ;  A!  a!  a3  dim3  DROP  m m3  0  DO  CR  .  "  Row  "  I  .  a  3  I  R !  LOOP  ; 

1  1 

12 

1 

14 
l  5 


214  LIST 


0 

( 

Mali- 

i  x 

and 

Hatr  i  x 

Row  and  Column  Input  and 

Ou t  pu t 

) 

i 

: 

Cl  ! 

j  ! 

a  f* 

a  3  dim  3 

DROP  m ’  m3  0 

DO  CR  . ”  a  ( 

"  i 

R  * 

ii 

ii 

5 

z' 

j3 

. 

it  j  —  ii 

IN#  I  j3  AA' 

LOOP  ; 

yt 

£ 

Cl  . 

j  f 

a  ! 

a 3  dim3 

DROP  m !  m3  0 

DO  CR  . "  a ( 

m  i 

. 

ii 

ii 

4 

j  3 

e 

it  ^  _  li 

I  j3  A A3  N- 

LOOP  ; 

c~ 

; 

R 1  ! 

i  1 

a  ! 

a 3  dim® 

n !  DROP  n3  0 

DO  CR  . "  a  ( 

"  i  < 

D  . 

. 

li 

* 

t 

CD 

I  . 

ii 

)  =  " 

IN#  i 3  I  AA! 

LOOP  ; 

“7 

; 

R 1  . 

i  S 

a  f 

a®  d i m3 

n  !  DROP'  n 3  O 

DO  CR  . "  a ( 

*'  i  < 

D  - 

. 

5 

8 

I  . 

,  “ 

)  = 

■'  i  3  I 

A A3  N.  LOOP 

9 

; 

A 1  . 

a  ! 

a  3 

dim3  DROP  m!  m3  0  DO 

CR  . "  Row  " 

I  . 

aa> 

i 

R1  . 

10 

LOOP  ; 

1  1 

2 

A1  ' 

a  : 

d  i  m3  DROP  m !  m3  0  DO 

CR  . "  Row  " 

I  . 

a Q 

i 

R 1  ! 

12  LOOP  ; 

i  3 


15 
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215  LIST 

O  (  Matrix-Scalar  Mul  ti  pi  i  cat  i  on ;  Matrix  Fill,  Clear;  Subrs,  ) 

1  CODE  (a*)  m  LDA  n  MUL  0  1  MOV  adr  LDA  65520  #  W  MOV 

2  BEGIN  O  N>  FLD  O  DS  LSG  R64  W  )  FMUL  R64  W  )  FSTP  O  INC  LOOP 

3  O  N)  FSTP  2  2  BUB  2  DS  LSG  NEXT 

4  :  a#  dim®  n!  mi  <a$)  ; 

5  CODE  (a-!)  m  LDA  n  MUL  O  1  MOV  adr  LDA  65520  #  W  MOV 

6  BEGIN  O  DS  LSG  R64  W  )  FST  O  INC  LOOP  O  N)  FSTP  2  2  SUB 

7  2  D3  LSG  NEXT 

S  :  a—  i  dim®  n!  mi  (a.—  !)  ;  :  clr  0.0  a—  i  ; 

9  :  < square!?  dim®  n!  n3  =  NOT  ABORT"  Not  Square  “  ; 

10  CODE  (12!)  I  PUSH  R  PUSH  65528  #  I  MOV  n  LDA  adr  2  MOV 

11  2  W  MOV  0  1  MOV  FLD 3  BEGIN  1  R  MOV 

12  O  1  MOV  FLDZ  BEGIN  2  DS  LSG  F;64  I  )  FST  2  INC  LOOP 

13  O  N)  FSTP  W  DS  LSG  R64  I  )  FST  O  W  ADD  W  INC  R  1  MOV  LOOP 

14  O  N)  FSTP  2  2  SUB  2  DS  LSG  R  POP  I  POP  NEXT 

15  :  12!  (square)  <I2')  ; 


216  LIST 

O  (  Exchange  Rows,  e.q.  7  X  ’  Y  5  3  excR'l  ) 

1  ~  CODE  excRl  2  POP  O  POP  1  POP  W  POP  I  PUSH  1  I  MOV  W  )  0  ADD 
21)2  ADD  4  W)  1  MOV  2  W)  W  MOV  65520  #  I  MOV  BEGIN  0  DS  LSG 

3  R64  I  )  FLD  2  DS  LSG  R64  I  )  FLD  0  DS  LSG  F<64  I  )  FSTP  2  DS  LSG 

4  R64  I  )  FSTP  W  O  ADD  W  2  ADD  LOOP  2  2  SUB  2  DS  LSG  I  POP  NEXT 

5  (  Exchange  Columns,  e.g.  7  X  7  Y  4  7  excCl  ) 

6  "  CODE  excCl  U  O  MOV  U  POP  R  1  MOV  R  POP  I  2  MOV  I  POP  W  POP 

7  O  PUSH  1  PUSH  2  PUSH  2  W)  1  MOV  U  O  MOV  2  W)  MUL  W  )  0  ADD 

B  O  W  MOV  R  O  MOV  2  I)  MUL  I  )  O  ADD  65504  #  I  MOV  BEGIN  O  INC 
9  W  INC  O  DS  LSG  R64  I  )  FLD  W  DS  LSG  R64  1  )  FLD  0  DS  LSG 

1 0  R64  I  )  FSTP  W  DS  LSG  R64  I  )  FSTP  LOOP  2  2  SUB  2  DS  LSG 

1 3  I  POP  R  POP  U  POP  NEXT 

IS'  :  <  d  i  m  >  b !  t>®  dim®  n!  m!  adr  a)  c!  a!  a®  dim®  n®  =  SWAP'  m®  =  AND 

13  NOT  AEtORT "  Inequal  Dimensions  “  ; 

14  (  Exchange  Matrices,  e.q.  7  X  7  Y  excAl  ) 

15  ^  ;  excAl  <dim>  n®  O  DO  a®  b®  I  I  excRl  LODF'  ; 


217  L.IST 

O  (  Matrix  Addition  10th— .019  sec.  50th— . 165  sec.  ) 

3  CODE  ( A+ )  m  LDA  n  MUL  O  1  MOV  adr  LDA  c  2  MOV 

2  65520  #  W  MOV  BEGIN  O  DS  LSG  R64  W  )  FLD  2  DS  LSG  R64 

3  W  >  FADD  R64  W  )  FSTP  O  INC  2  INC  LOOP  2  2  SUB  2  DS  LSG  NEXT 

4  i  A+  <dim>  (A+)  ; 

5  <  Matrix  Transfer,  e.q.  7  X  7  Y  1  2  ->  ) 

6  CODE  (->>  I  PUSH  m  LDA  n  MUL  O  1  MOV  adr  LDA  c  2  MOV 

7  i  I  MOV  j  W  MOV  BEGIN  O  DS  LSG  R64  I  )  FLD  2  DS  LSG  (Continued  on  next  page) 
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(Listing  continued,  text  begins  on  page  70) 


8  R64  W  >  FSTP  O  INC  2  INC  LOOP  2  2  SUE  2  DS  LSG  I  POP  NEXT 

9  :  ~>  2SWAP  <dim>  1  =  IF  65520  ELSE  65528  THEN  j  !  1  =  IF  65520 

10  ELSE  65528  THEN  i  !  <->>  ; 

11  <  Exchange  o-f  Interlaced  Matrices,  e.g.  ’  X  ex c.  1 2  ) 

12  "  CODE  (exc 12)  I  PUSH  m  LDA  n  MUL  0  1  MOV  adr  LDA  65520  #  1  MOV 

13  65528  #  W  MOV  DS  PUSHS  BEGIN  0  DS  LSG  R64  I  )  FLB  R64  W  )  ELD 

14  R64  I  )  FSTP  R64  W  )  FSTP  0  INC  LOOP  DS  POPS  I  POP  NEXT 

15  :  ex  cl  2  dim©  n!  m1  (excl2>  ; 


218  LIST 

0  <  Matrix  Transposition,  10th— .017  sec.  50th— .119  sec.  ) 

1  CODE  (TRNSP)  I  PUSH  R  PUSH  U  PUSH  65520  #  I  MOV  n  R  MOV  m  LDA 

2  0  IJ  MOV  R  MUL  O  DEC  adr  2  MOV  c  W  MOV  R  1  MOV 

3  BEGIN  1  ES  LSG  U  1  MOV  BEGIN  2  DS  LSG  R64  I  )  ELD  W  DS  LSG 

4  R64  I  >  FSTP  2  INC  R  W  ADD  LOOP  0  W  SUB  1  ES  SSG  LOOP  2  2  SUB 

5  2  ES  LSG  2  DS  LSG  U  POP  R  POP  1  POP  NEXT 

6  ;  TRNSP  b !  a*  b©  dim©  m‘  n!  adr©  c 1  a©  dim©  ri©  =  SWAP  m©  = 

7  AND  NOT  ABORT"  Nonconformable  "  (TRNSP)  ; 

8  (  Exchanging  Rows  o-f  Interlaced  Matrix,  e.g.  ’  X  *  Y  3  2  excR  ) 

9  ~  CODE  ex  cR  2  POP  O  POP  1  POP  W  POP  I  PUSH  U  PUSH 

10  1  I  MOV  W  )  O  ADD  65528  #  U  MOV 

131)2  ADD  4  W)  1  MOV  2  W)  W  MOV  65520  #  I  MOV  BEGIN  O  DS  LSG 

12  R64  I  )  FLD  R64  3  )  FID  2  DS  LSG  R64  I  )  FLD  R64  3  >  FLD 

.13  O  DS  LSG  R64  3  )  FSTP  R64  I  )  FSTP  2  DS  LSG  R64  3  )  FSTP 

14  R64  I  )  FSTP  W  O  ADD  W  2  ADD  LOOP  2  2  SUB  2  DS  LSG 

15  U  POP  I  POP  NEXT 


239  LIST 

0  (  Matrix  Multiplication,  10th-. 099  sec.  50th-  9.817  sec.  ) 

1  CODE  (A# )  I  PUSH  R  PUSH  U  PUSH  65520  4  I  MOV 

2  a  2  MOV  k  R  MOV  R  ES  LSG  c  O  MOV  m  1  MOV  1  R  MOV  BEGIN  1  PUSH 

3  b  W  MOV  n  1  MOV  BEGIN  1  PUSH  2  U  MOV  FLDZ 

4  1  ES  SSG  BEGIN  U  DS  LSG  R64  I  )  FLD  W  DS  LSG  W  INC 

5  R64  I  )  FMUL  R  U  ADD  1  N)  FADD  LOOP 

6  O  DS  LSG  F:64  I  )  FSTP  R  O  ADD  1  POP  LOOP 

7  2  INC  1  DS  LSG  c  LDA  O  INC  c  STA  1  POP  LOOP 

8  1  ES  LSG  U  POP  R  POP  I  POP  NEXT 

9  :  A*  c!  b!  a!  c©  dim©  n !  m!  adr©  c1  b©  dim©  n©  =  SWAP  k ! 

10  adr©  b I  a©  dim©  k©  =  SWAP  m©  =  adr©  a<  AND  AND  NOT 

11  ABORT"  Nonconf ormable  "  (A*)  ; 

12 

13 
3  4 
1  5 
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220  LIST 

0  (  Subroutines  for  Matrix  Inversion  ) 

1  CODE  (INV1)  I  PUSH  n  LDA  0  1  MOV  j  W  MOV 

2  W  MLJL  adr  W  ADD  W  0  ADD  0  DS  LSB  65520  #  I  MOV  R64  I  )  FLD 

3  FLD1  1  N )  FDI V  REV  W  2  MOV  65528  #  W  MOV  1  O  MOV  BEGIN  O  N)  FLD 

4  2  DS  LSB  R64  I  )  FMUL  R64  I  >  FSTP  O  N)  FLD  R64  W  )  FMUL  R64 

5  W  )  FSTP  O  2  ADD  LOOP  2  2  SUB  2  DS  LSG  I  POP  O  N)  FSTP  NEXT 

6  ~  CODE  < INV2)  I  PUSH  R  PUSH  U  PUSH  65520  #  I  MOV  65528 

7  #  W  MOV  n  LDA  O  1  MOV  i  MUL  adr  O  ADD  O  R  MOV  i  O  ADD  b  STA 

8  adr  LDA  0  ES  LSG  O  #  j  MOV  BEGIN  1  PUSH  R  1  MOV  b  1  SUB  0=  NOT 

9  IF  R  DS  LSG  R64  I  >  FLD  FCHS  1  1  SUB  1  DS  LSG  i  LDA  k  STA 

10  .U  ES  SSG  U  2  MOV  j  2  ADD  k  U  ADD  n  LDA  O  1  MOV  BEGIN  O  N) 

11  FLD  U  DS  LSG  R64  I  >  FMUL  2  DS  LSG  R64  I  )  FADD  R64  I  )  FSTP 

12  O  N)  FLD  U  DS  LSG  R64  W  )  FMUL  2  DS  LSG  R64  W  )  FADD  0  2  ADD 

13  R64  W  )  FSTP  O  U  ADD  LOOP  O  N>  FSTP  THEN  1  1  SUB  1  DS  LSG 

14  R  INC  j  LDA  O  INC  j  STA  1  POP  LOOP  1  1  SUB 

15  1  FS  LSG  U  POP  R  POP  I  POP  NEXT 


221  LIST 

O  C  Matrix  Inversion,  10th-. 217  sec.,  50th-  22.168  sec.  ) 

1  ;  INV  a1  a®  -(square)  n®  m !  (12!  )  nS  O  E>0  n®  I  j  !  j®  DO  Ik!  I 

2  j®  AA®  F0=  NOT  IF  LEAVE  THEN  LOOP  a®  a®  j®  k®  excR 

3  ( I N V 1 )  I  i !  ( I NV2)  LOOP  a®  a®  2  1  ->  ; 

4 

5 

6 
7 
0 
9 

10 
1 1 
12 
1  3 

14 

15 


222  LIST 

O  (  Determinant,  .074  sec. -10th,  4.965  sec.-50th  Order  ) 

1 

2  CODE  ( DET )  J  PUSH  R  PUSH  U  PUSH  n  1  MOV  k  LDA  O  R  MOV 

3  65520  #  I  MOV  O  1  SUB  n  MUL  n  2  MOV  adr  O  ADD  O  U  MOV 

4  R  O  ADD  j  U  ADD  BEGIN  O  N>  FLD  O  DS  LSG  R64  I  >  FMUL 

5  U  DS  LSG  R64  I  )  FADD  R64  I  )  FSTP  2  O  ADD  2  U  ADD  LOOP  O  N> 

6  FSTP  2  2  SUB  2  DS  LSG  U  POP  R  POP  I  POP  NEXT 

7  :  D 1  k®  k®  A A®  FNEGATE  1/N  n®  k®  1+  DO  FDUP  I  k®  A A®  F*  I  j! 

8  (DET)  LOOP  F  DROP  ; 

9  j  D2  n®  k®  1+  DO  I  k®  AA®  FO=  NOT  IF  n®  k®  DO  J  I  AA®  k®  I  AA® 

10  J  I  AA!  k®  I  AA!  LOOP  b®  NEGATE  b!  D1  LEAVE  THEN  LOOP  ; 

11  ;  DET  a!  a®  (square)  a®  a®  1  2  — >  1  b!  n®  1—  O  DO  Ik!  II 

(Continued  on  next  page) 
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Fast  Matrix  Operations 

( Listing  continued,  text  begins  on  page  70) 


12  AA®  FO=  NOT  IF  D1  ELSE  D2  THEN  LOOP  1,0  nS  O  DO  I  I  AA®  F*  LOOP 

13  b®  >N  F*  a 3  a®  2  1  ->  ; 

14 

15 


223  LIST 

O  C  Column  Sort,  500  Numbers— .740  sec.  ) 

1  CODE  (SORT)  I  PUSH  R  PUSH  U  PUSH  65520  #  I  MOV  a  2  MOV  b  U  MOV 

2  2  ES  LSG  BEGIN  U  SHE  U  U  AND  O*  NOT  IF  a1  n  1  MOV  U  1  SUB 

3  0  0  SUB  j  ST A  BEGIN  j  R  MOV  BEGIN  2  ES  SSG  R  2  ADD  2  W  MOV  U  W 

4  ADD  2  DS  LSG  R64  I  )  FLD  W  DS  LSG  R64  I  )  FLD  1  N)  FCOM 

5  0  0  SUB  0  DS  LSG  a  FSTSW  a  LDA  SAHF  CS  IF  2  DS  LSG  R64  I  )  FSTP 

6  W  DS  LSG  R64  I  )  FSTP  U  R  SUB  0<  IF  0  0  SUB  THEN  ELSE 

7  O  N)  FSTP  O  O  SUB  O  N>  FSTP  THEN  SAHF  CS  NOT  UNTIL  O  O 

3  SUB  O  DS  LSG  j  LDA  O  INC  j  STA  1  0  CMP  0>  UNTIL  1  0  CMP  0< 

9  UNTIL  a®  THEN  0  O  SUB  0  DS  LSG  O  ES  LSG  U  POP  R  POP  I  POP  NEXT 


10 

1 1 

;  sortCl  af  dim® 
(SORT)  ; 

SWAP  m !  m® 

b  1 

b® 

1-  n  ! 

a®  * 

adr®  +  a ! 

12 

;  sortAl  dim®  n! 

m !  n®  m®  * 

b  ! 

b® 

1-  n  1 

adr® 

a!  (SORT) 

13' 

14 

15 


224  LIST 


0  (  Column  Sort,  500  Numbers— 1.0  sec.  ) 

1  CODE  ( SRT )  I  PUSH  R  PUSH  U  PUSH  65520  #  I  MOV  a  2  MOV  b  U  MOV 

2  2  ES  LSG  BEGIN  U  SHR  U  U  AND  0=  NOT  IF  a!  n  1  MOV  LI  1  SUB 

3  0  0  SUB  j  STA  BEGIN  j  R  MOV  BEGIN  2  ES  SSG  R  2  ADD  2  W  MOV  U  W 


4  ADD  2  DS  LSG  R64  I  )  FLD  W  DS 

5  0  0  SUB  O  DS  LSG  a  FSTSW  a  LDA 

6  W  DS  LSG  R64  I  )  FSTP  R64  8  I) 

7  LSG  R64  8  I)  FSTP  2  DS  LSG  R64 

8  THEN  ELSE  0  N)  FSTP  O  O  SUB  O 

9  0  0  SUB  0  DS  LSG  j  LDA  O  INC  j 
10  UNTIL  a®  THEN  O  O  SUB  O  DS  LSG 
tl  :  sortC  a!  dim®  SWAP  m1  m®  b 

12  (SRT)  ; 

13  i  sort  A  dim®  n!  m1  n®  m®  %  b 

1 4 


LSG  R64  I  )  FLD  1  N)  FCOM 
SAHF  CS  IF  2  DS  LSG  R64  I  >  FSTP 
FLD  2  DS  LSG  R64  8  I)  FLD  W  DS 
8  I)  FSTP  U  R  SUB  0<  IF  O  O  SUB 
N)  FSTP  THEN  SAHF  CS  NOT  UNTIL 
STA  1  0  CMP  0>  UNTIL  1  O  CMP  0< 

O  ES  LSG  U  POP  F:  POP  I  POP  NEXT 

b®  1-  n!  a®  t  ad r®  +  a! 

b®  1—  n!  adr®  a*  (SF:T)  ; 
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o  -J  CODE  polvRl  O  POP  W  POP  W  )  O  ADD  4  W>  i  MOV  2  W)  2  MOV 

1  65520  #  W  MOV  FLD1  1  DEC  0  DS  i._SG  R64  W  >  FST  BEGIN 

2  1  N )  FMUL  NO  2  0  ADE>  0  DS  L.3G  R64  W  )  FST  LOOP  O  N)  FSTP 

3  O  N >  FSTP  2  2  SUB  2  DS  LSG  NEXT 

4  CODE  polyVl  W  POP  W  )  0  MOV  2  W>  1  MOV 

5  65520  #  W  MOV  FL.D1  i  DEC  O  DS  LSG  R64  W  )  FST  BEGIN 

o  1  N)  EMU.-  NO  O  INC  O  Do  LSG  R64  W  )  FS!  LOOP’  U  N)  FSTF' 

7  O  N !  FSTP  2  2  SUB  2  DS  LSG  NEXT 

8  CODE  V %  W  FOP  W  )  O  MOV  2  W)  1  MOV  W  POP  W  )  W  MOV 

?  I  PUSH  65520  #  I  MOV  FLDZ  BEGIN  O  DS  LSG  R64  I  )  FLD  W  DS  LSG 

10  R64  I  5  FMUL  O  INC  W  INC  1  N)  FADD  LOOP  O  O  SUB  0  DS  LSG 

11  I  POP  NEXT 

12 

13 

14 

15 


226  LIST 

O  (  Matrix  Transpose -Mul ti pi y,  10th-. 093  sec.  50th—  9.818  sec.  ) 

1  CODE  IT*)  I  PUSH  R  PUSH  U  PUSH  k  R  MOV  b  2  MOV  c  O  MOV 

2  65520  #  I  MOV  n  1  MOV  BEGIN  1  PUSH  adr  W  MOV  m  1  MOV 

3  BEGIN  1  ES  LSG  2  U  MOV  FLDZ  R  1  MOV  BEGIN  U  DS  LSG  R64  I  )  FLD 

4  W  DS  LSG  R64  I  )  FMUL  W  INC  U  INC  1  N>  FADD  LOOP  0  DS  LSG 

5  R64  I  >  FSTP  O  INC  1  ES  SSG  LOOP  1  DS  LSG  R  2  ADD  1  POP 

6  LOOP  1  D3  LSG  1  ES  LSG  LJ  POP  R  POP  I  POP  NEXT 

7  :  r %  d i  rtO  n!  !  adr 3  c!  d i iT: 0  n 5)  adr3  b!  =  SWAP  k!  SWAP  dim®  obi) 

8  —  SWAP  k 0  =  AND  AND  NOT  ABORT"  Nonconf ormabl e  "  (T*)  ; 

9 

10 
1  1 

12 

t  -T 
>  •-’» 

14 

15 


227  LIST 

0  CODE  (polyAl)  I  PUSH  R  PUSH  65520  #  I  MOV  m  LDA  n  2  MOV  2  DEC 

1  adr  W  MOV  O  1  MOV  BEGIN  1  ES  LSG  W  F;  MOV  R  DS  LSG  R64  I  )  FLD 

2  FLD1  R64  I  )  FST  2  1  MOV  BEGIN  O  R  ADD  R  DS  LSG  1  N)  FMUL  NO 

3  R64  I  )  FST  LOOP  O  N>  FSTP  O  N>  FSTP  W  INC  1  ES  SSG  LOOP 

4  1  ES  LSG  1  DS  LSG  R  POP  I  POP  NEXT 

5  ~  ;  polyAl  dimS)  n!  m !  (polyAl)  ? 


8 
9 
10 
1  i 
1  2 

13 

14 

1 5  End  Listing 
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DR.  DOBB’S  CLINIC 


by  D.  E.  Cortesi,  Resident  intern 


Two  Gets  You  Ten 

Some  time  back  we  posed  a  question 
regarding  binary  floating  point  versus 
decimal  floating  point.  There  are  some 
ratios  (fractions)  that  can  be  represented 
by  a  finite  number  of  decimal  digits,  but 
which  require  an  infinite  number  of  bi¬ 
nary  digits.  For  example,  the  fraction  1/5 
can  be  represented  exactly  in  decimal  (as 
0.2),  but  it  becomes  a  “repeating  binary” 
when  you  attempt  to  represent  it  as  a 
binary  fraction  (namely,  0.00110011...). 
It  takes  an  infinite  number  of  bits  to  rep¬ 
resent  exactly  1/5  in  binary.  Since  any 
machine  representation  is  woefully  finite, 
it  is  quite  literally  impossible  to  store  a 
value  of  1/5  in  a  system  that  uses  binary 
float.  You  may  enter  0.2,  but  what  is 
stored  is  0.199...,  for  however  many 
effective  digits  the  system  supports. 

Ah  yes,  the  question.  There  are  ratios 
that  have  a  finite  representation  in  deci- 
nal  but  not  in  binary;  we  asked  if  there 
were  also  ratios  that  have  a  finite  repre¬ 
sentation  in  binary  but  not  in  decimal? 
David  Oster  wrote  to  say  that  there  were 
not,  and  Robert  Pirko  provided  the  fol¬ 
lowing  amplification. 

“David  Oster  is  correct  that  all  frac¬ 
tions  which  have  a  finite  representation  in 
binary  also  have  one  in  decimal.  To  see 
why,  note  that  any  finite-length  decimal 
number  can  be  written  as 

P 

d  =  -  (eq.  1) 

10n 

where  p  and  n  are  integers.  For  example, 

0.35  =  35/ 1 02 

0.357  =  357/  1 03 

“Similarly,  a  finite-length  binary 
number  has  the  form 


q 


where  q  and  m  are  integers.  For  example, 

0.101  =  5/ 23  =  0.625  decimal 
0.1011  =  11/24  =  0.6875  decimal 
ll'e  can  multiply  the  top  and  bottom  of 
equation  2  by  a  constant  of  5™ 

q  *  5m  q  *  5m 

b  =  -  =  -  (eq.  3) 

2m*5m  10m 

but  this  is  equivalent  to  equation  1,  so 
the  value  b  can  thus  be  precisely  specified 
in  m  decimal  digits.” 

Pirko  goes  on  to  note  an  interesting 
implication  of  this.  That  the  denominator 


of  equation  3  is  1 0m  implies  that  it  could 
take  as  many  as  m  decimal  digits  to  repre¬ 
sent  an  m  -bit  binary  fraction  in  decimal. 
If  there  are  56  bits  in  the  fraction  (as  in 
an  MBASIC  double-precision  number), 
some  representable  values  will  require  56 
digits  for  exact  representation  in  decimal 
—  but  no  decimal -display  routine  will 
show  them  (as  MBASIC  only  displays 
16  significant  digits). 

We  are  beginning  to  see  a  little  more 
clearly  the  relationship  between  binary 
and  BCD  floating-point  machine  arith¬ 
metic.  The  problems  unique  to  binary 
arise  during  input  and  output  conversions. 
On  input,  certain  decimal  fractions  are 
truncated  (1/5  becoming  0.199...).  On 
output,  certain  binary  values  are  trun¬ 
cated.  A  representation  using  BCD  will 
suffer  neither  of  these  conversion  errors. 

Is  either  system  significantly  better 
during  the  arithmetic  operations  that 
happen  between  input  and  output?  Math¬ 
ematically  speaking,  we  suspect  not.  All 
operations  will  be  done  on  a  finite  num¬ 
ber  of  digits  (whether  binary  ones  or  deci¬ 
mal  ones);  therefore  either  method  will 
incur  roundoff  errors  and  all  the  pecu¬ 
liarities  they  induce.  Practically  speaking, 
the  errors  might  differ  somehow  in 
quality  and  so  affect  a  user’s  perception 
of  a  system’s  accuracy.  Comments, 
whether  theoretical  or  based  on  experi¬ 
ence,  are  still  welcome  on  this  point.  We 
ask  again,  has  anybody  run  comparable 
problems  on  a  pair  of  comparable  systems 
(e.g.,  binary  BASCOM  versus  decimal 
CB80)? 

If  you  are  having  trouble  with  binary 
arithmetic,  you  should  note  a  letter  from 
Paul  Weras,  published  in  the  May  9  edi¬ 
tion  of  InfoWorld.  He  suggests  that  the 
PRINT  USING  statement  of  BASIC  will 
fix  most  of  the  problems  people  have 
with  money  output,  giving  as  an  example 

10FMTS  =  “#.##” 

20  A  =  9.899999 

30  PRINT  USING  FMT$;  A 

which  results  in  a  display  of  9.90  —  the 
numeric  format  item  apparently  having 
caused  rounding. 


Cheap  Thrills  Dept. 

We  are  always  happy  to  hear  about 
good,  cheap  software,  so  we  were  pleased 
to  get  a  note  from  Jim  Laurino  of  Phila¬ 
delphia,  Pennsylvania.  He  writes  a  whole¬ 
hearted  recommendation  for  PE,  a  full¬ 


80 

392 


screen  editor  for  the  IBM  PC.  “It  has 
unique  features,”  he  says,  “that  place  it 
head  and  shoulders  above  similar  products. 
IBM,  which  sells  it  under  part  number 
6024051,  doesn’t  seem  to  appreciate  it. 
The  sales  people  I  have  spoken  to  had  no 
experience  with  it.  Perhaps  because  it  is 
priced  at  only  $100,  people  assume  it’s 
not  very  good.” 

One  of  PE’s  best  features,  it  seems,  is 
that  it  allows  you  to  program  the  values 
of  all  99  key  operations,  giving  any  alt-, 
ctl -,  shift,  or  normal  stroke  a  value  that 
can  apparently  be  a  single  character  or  a 
lengthy  string  including  mixed  data  and 
editor  operations.  The  key  definitions  are 
read  from  a  “pe.pro”  file  when  the  editor 
starts  up,  and  the  active  definitions  can 
be  edited  as  if  they  were  a  file  during  the 
edit  session.  PE  can  also  edit  the  disk 
directory  as  if  it  were  a  file,  and  Laurino 
gives  some  keystroke  definitions  that 
allow  him  to  load  the  disk  directory  and 
convert  it  into  a  batch  command  file  with 
a  half-dozen  keystrokes. 

“You  can  have  up  to  20  files  open  at 
once,”  Laurino  says,  “including  directo¬ 
ries  and  internal  files  for  key  definitions 
and  changed  lines.  You  may  mark  text  in 
any  file  and  copy  it  to  any  other.  If  you 
have  only  two  files  open,  typing  F8 
rapidly  will  switch  you  between  them 
so  quickly  that  differences  appear  to 
flicker,  giving  you  a  visual  comparison 
function.  PE  knows  about  and  can  use  all 
the  memory  you  have  as  a  buffer,  and 
will  overflow  to  disk  when  it  runs  out.” 


The  AGGHHH!  Program 

Our  CP/M  Plus  Bios  is  still  a  wee  bit 
shaky  and  every  once  in  a  while  it  takes 
off  to  never-never  land.  Alas,  this  usually 
happens  when  we  are  in  the  middle  of 
editing.  The  first  time  we  lost  the  system 
after  an  hour’s  typing,  we  got  the  file 
back  by  loading  up  SID,  prowling  around 
the  shattered  remains  of  the  PeachText 
edit  buffer,  and  finally  hand-assembling  a 
little  program  that  wrote  the  still-readable 
text  to  disk  as  a  file. 

The  second  time  it  happened,  we  got 
serious  and  wrote  the  Panic  program.  Panic 
will  recover  whatever  remains  in  storage 
of  a  PeachText  file  after  a  system  crash. 
Those  who  use  PeachText  version  2  might 
be  interested  in  it  (Listing,  page  81). 

The  text  buffer  in  storage  begins 
with  a  byte  of  FFh  and  ends  with  another 
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FFh.  Between  the  two,  there  should  be 
nothing  but  ASCII  data.  There  may  be  a 
large  number  of  NUL  (OOh)  bytes;  these 
are  not  saved.  Block  markers  seem  to  be 
represented  as  Olh.  There  are  notabs;they 
are  apparently  expanded  to  blanks  when 


the  file  is  loaded.  The  CR  is  a  line-marker 
but  it  is  not  followed  by  a  LF,  so  Panic 
has  to  insert  one.  All  this  should  also  be 
true  of  earlier  versions  of  PeachText 
(Magic  Wand),  but  the  address  “Peaches,” 
where  Panic  expects  to  find  the  leading 


FFh,  would  probably  be  different.  »»j 

( Listing  begins  below) 


Clinic  Listing 


PANIC  fileref 

Save  the  contents  of  a  crashed  Magic  Wand's  edit  buffer 

The  buffer  should  begin  at  41F8  (PeachText)  with  a  byte  of  FF. 
Data  follows  to  a  second  FF.  The  data  should  be  all-ASCII  but 
it  may  include  control  characters: 


;  CR 

( ODh) 

-a  LF  (OAh) 

must  be  added  to  each  one 

;  lf 

(OAh) 

-  may  appear 

and  is  OK 

;  FF 

(OCh) 

-  may  appear 

("page  mark")  and  is  ok 

;  TAB 

(09h) 

-  does  NOT 

appear . 

;  S0H 

(Olh) 

-  seems  to 

be 

a  "block  marker"  —  discard 

;  NUL 

(OOh) 

-  sometimes  appears  —  discard 

5 

CSEG 

0000 

314000 

lxi 

sp, Stack 

0003 

C37500 

jmp 

Main 

000D 

= 

CR 

equ 

ODh 

000A 

= 

LF 

equ 

OAh 

0020 

= 

Blank 

equ 

20h 

0024 

= 

Dollar 

equ 

001 A 

= 

Eof 

equ 

26 

41F8 

= 

Peaches 

equ 

4lF8h 

5 

where  the  edit  buffer  should  be 

005C 

= 

Feb 

equ 

5Ch 

5 

a  fileref  MUST  BE  SUPPLIED 

0080 

= 

Record 

equ 

0080h 

5 

file  buffer  for  output 

0005 

= 

Bdos 

equ 

5 

y 

Bdos  vector 

0009 

= 

TypeMsg 

equ 

9 

y 

type  a  string  to  $ 

0013 

= 

Erase 

equ 

19 

y 

erase  function 

0016 

= 

Make 

equ 

22 

y 

make  new  file 

0015 

= 

Write 

equ 

21 

y 

sequential  write 

0010 

= 

Close 

equ 

16 

y 

close  output  file 

001  A 

= 

Set  Ad 

equ 

26 

y 

set  file  buffer  address 

0006 

4669727374NoFF 

db 

'First 

FF 

not  found ' ,CR,LF, Dollar 

00  IB 

5365636F6ENoEnd 

db 

'Second 

FF  not  found ',CR,LF, Dollar 

0031 

55736l6765NoFile 

db 

'Usage 

is 

PANIC  filespec ', CR , LF , Dollar 

004C 

536F6D6520Done 

db 

'Some  data 

saved,  use  with  care  '  ,CR,LF, Dollar 

Quit:  ; 

come 

here  with 

DE- 

>  one  of  above  messages,  to  quit 

006D 

OE09 

mvi 

c , TypeMsg 

006F 

CD0500 

call 

Bdos 

0072 

C30000 

jmp 

0 

5 

Main : 

5 

;  First 

off, 

make  sure 

we 

have  a  starting  FFh 

(Continued  on  next  page) 
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SI  to 


Clinic  Listing 

(Listing  continued,  text  begins  on  page  80) 

0075 

21F841 

lxi 

h, Peaches 

0078 

7E 

mov 

a  ,m 

0079 

3C 

inr 

a 

i 

is  it  FF  (goes  to  00)? 

007A 

CA8300 

jz 

Main2 

5 

(yes,  fine) 

007D 

110600 

lxi 

d , NoFF 

9 

no  —  PeachText  overlaid? 

0080 

C36DOO 

jmp 

Quit 

5 

;  Then 

make  sure  we  have 

an  ending  FF  at  a  higher  address, 

;  but 

still  less  than  the 

start  of  the  Bdos 

0083 

3A0700 

5 

Main2 : 

Ida 

Bdos+2 

5 

page-address  of  Bdos 

0086 

47 

mov 

b,a 

5 

to  B  for  comparisons 

0087 

1 1 1  BOO 

Main 3: 

lxi 

d ,  No  End 

> 

message  for  if  we  quit 

008A 

23 

inx 

h 

008B 

7C 

mov 

a  ,h 

008C 

B8 

emp 

b 

5 

still  below  Bdos? 

008D 

D26D00 

jnc 

Quit 

5 

(no,  give  up) 

0090 

7E 

mov 

a,m 

0091 

3C 

inr 

a 

9 

found  the  2nd  FF  yet? 

0092 

CA9B00 

jz 

Main4 

9 

(yes,  carry  on) 

0095 

FA6D00 

jm 

Quit 

9 

(no,  found  garbage  (code?)) 

0098 

C38AOO 

jmp 

Main3 

9 

(no,  but  still  in  Ascii  data) 

9 

;  Now 

make  sure 

that  we 

have  a  filespec  to  work  with 

009B 

3A5D00 

9 

Main4: 

Ida 

Fcb+1 

009E 

FE20 

cpi 

Blank 

5 

omitted  first  operand? 

00A0 

113100 

lxi 

d , NoFile 

00A3 

CA6D00 

jz 

Quit 

5 

(yes,  bail  out  to  try  again) 

5 

;  Get 

rid  of  any  existing 

file  of  this  name  (well,  this  IS 

;  a  crisis,  you 

• 

know) 

00A6 

1 15C00 

lxi 

d ,  Feb 

00A9 

0E1 3 

mvi 

c, Erase 

5 

erase 

00AB 

CD0500 

call 

Bdos 

5 

..the  named  file 

00AE 

115C00 

lxi 

d ,  Feb 

00B1 

0E1 6 

mvi 

c ,Make 

5 

make 

00B3 

CD0500 

call 

Bdos 

5 

..the  named  file 

00B6 

118000 

lxi 

d, Record 

00B9 

0E1 A 

mvi 

c, Set Ad 

9 

set 

00BB 

CD0500 

call 

Bdos 

9 

..the  file  buffer  address 

;  set 

up  registers  for  the  loop  and  get  to  work 

OOBE 

118000 

9 

lxi 

d , Record 

;  DE->next  outbyte 

00C1 

21F941 

lxi 

h,Peaches+1  ;  HL->next  inbyte 

00C4 

7E 

loop: 

mov 

a,m 

9 

get  this  byte, 

00C5 

23 

inx 

h 

9 

..and  point  to  next  one 

00C6 

B7 

ora 

a 

9 

is  this  FF? 
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00C7 

FAF200 

jm 

closeit 

5 

(yes,  finish  up) 

OOCA 

FEOA 

cpi 

LF 

5 

is  it  less  than  LF? 

OOCC 

DAC400 

jc 

loop 

5 

(yes,  ignore  00.. 09) 

OOCF 

CDDCOO 

call 

onebyte 

whatever,  write  it 

00D2 

FEOD 

cpi 

CR 

5 

CRs  need  LFs  in  files 

00D4 

3E0A 

mvi 

a,LF 

00D6 

CCDCOO 

cz 

onebyte 

5 

add  LF  to  every  CR 

00D9 

C3C400 

jmp 

loop 

5 

and  repeat 

here  write  the  byte  in  A,  sending  a  record  to  disk 
as  necessary.  Preserve  current  byte  in  A. 


onebyte : 


00DC 

12 

stax 

d 

;  store  the  byte 

00DD 

1C 

inr 

e 

;  step  the  pointer 

00DE 

CCE200 

cz 

writit 

;  (write  block  if  full) 

00E1 

C9 

ret 

send  one  record  to  disk,  reset  out pointer  in  DE, 
preserve  A,  HL 


writit : 


00E2 

F5 

push 

psw 

5 

block  full,  save  byte 

00E3 

E5 

push 

h 

5 

. . and  HL 

00E4 

115C00 

lxi 

d ,  Feb 

00E7 

0E15 

mvi 

c , Write 

and  write 

00E9 

CD0500 

call 

Bdos 

J 

one  block 

00EC 

118000 

lxi 

d , Record 

5 

reset  outpointer 

00EF 

El 

pop 

h 

5 

recover  text  pointer 

00F0 

FI 

pop 

psw 

5 

and  byte 

00F1 

C9 

ret 

;  finish  up  the  saved  file  by  closing  it 
5 

closeit : 


00F2 

3E0D 

mvi 

a,CR 

tack  on  a  newline 

00F4 

CDDCOO 

call 

onebyte 

00F7 

3E0A 

mvi 

a,  LF 

5 

just  to  be  safe 

00F9 

CDDCOO 

call 

onebyte 

00FC 

3E1A 

mvi 

a ,  Eof 

5 

and  an  eof 

00FE 

CDDCOO 

call 

onebyte 

0101 

ID 

dcr 

e 

5 

if  we  didn't  just  start  a  record 

0102 

FCE200 

cm 

writit 

5 

(ie,  80  goes  to  7F)  then  write  last 

0105 

115C00 

lxi 

d ,  Feb 

0108 

0E1 0 

mvi 

c, Close 

0 1 0A 

CD0500 

call 

Bdos 

01 0D 

1 14C00 

lxi 

d,Done 

5 

reassure  user 

0110 

C36DOO 

jmp 

Quit 

5 

and  exit 

5 

DSEG 

0000 

ds 

64 

stack: 

0040 

end 

End  Listing 
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CP/M  EXCHANGE 


by  Robert  Blum 


This  issue  marks  the  first  anniversary 
of  the  CP/M  Exchange.  The  intent  of  this 
column  is  the  same  today  as  it  was  one 
year  ago:  to  provide  a  forum  for  CP/M 
users  to  share  their  experiences.  It  makes 
no  difference  whether  you  are  a  first  time 
CP/M  user  or  have  been  using  it  for  many 
years,  the  CP/M  Exchange  is  your  column. 
If  you  have  questions  send  them  along.  I 
will  try  to  answer  them  myself  or  seek 
counsel  from  the  other  readers.  On  the 
other  hand,  your  experiences  and  solu¬ 
tions  to  problems  can  benefit  others.  It’s 
been  an  exciting  year.  Numerous  subjects 
have  been  reviewed  and  your  response  has 
been  gratifying.  Here’s  to  you  and  the 
next  twelve  months. 


In  Retrospect 

The  most  popular  subject  covered  in 
the  past  year  was  communications.  Gene 
Head’s  MBOOT  program  was  greeted  with 
a  flurry  of  mail;  and  even  several  months 
later,  I  still  receive  an  occasional  letter.  In 
reviewing  all  the  mail  addressed  to  com¬ 
munications,  it’s  obvious  that  going  online 
for  the  first  lime  can  be  a  frustrating 
experience.  In  a  few  letters  it  was  made 
clear  that,  if  a  significant  investment  in 
hardware  had  not  been  made,  the  whole 
project  would  have  been  scrapped.  Al¬ 
though,  once  the  problems  were  worked 
out,  the  experience  of  being  able  to  dial 
into  systems  around  the  country  and 
peruse  the  myriad  pieces  of  free  software 
made  the  effort  worthwhile. 

Before  attempting  to  dial  into  a  re¬ 
mote  system  for  the  first  time,  a  little 
extra  preparation  is  necessary.  Keep  in 
mind  that  the  clock  doesn’t  stop  while 
you  are  figuring  out  a  problem.  Every 
minute  saved  on  a  coast-to-coast  call  can 
represent  a  substantial  savings.  First, 
study  and  restudy  the  documentation. 
It’s  important  to  understand  what  is 
about  to  happen  and  the  responses  to  any 
error  messages.  Second,  make  a  command 
reference  card.  This  card  will  become 
your  best  friend  the  first  time  you  can’t 
remember  how  to  respond  to  a  message. 
Third,  take  advantage  of  the  many  long 
distance  phone  services  that  offer  reduced 
rates.  If  no  discount  phone  service  is 
available  in  your  area,  wait  for  weekends 
or  evenings  when  rates  are  reduced.  Last, 
try  to  find  a  local  system  to  experiment 
with  before  going  to  the  long  lines.  It’s 
important  to  verify  that  your  system  is 
operational  before  committing  yourself 
to  long  distance  phone  bills. 


MBOOT  Revisited 

Dr.  David  DuPuy,  of  Lexington,  Vir¬ 
ginia,  wrote  to  share  his  experiences  and 
changes  to  MBOOT  (see  Figure  1,  page 
87)  for  the  Morrow  MULT/IO  board. 
He  writes: 

“Your  section  on  using  XMODEM 
was  very  useful;  I  had  no  idea  of  the 
protocol  with  XMODEM.  It  would  be 
very  useful  to  many  of  your  readers  to 
give  the  sequence  required  to  ‘unsqueeze’ 
a  file.  I  had  a  little  difficulty  in  locating 
the  unsqueeze  program  and  learning  the 
proper  commands  to  run  the  program. 
The  name  of  the  file  on  the  RCP/M 
I  used  (Ratoff’s)  was  USQ-15.0BJ. 
After  downloading  this  file,  rename  it 
to  USQ-15.COM  and  then  run  it  with 
‘USQ-15  PROG.AQM’.  ” 

Dr.  DuPuy  goes  on  to  say  that  he  has 
started  work  on  converting  MBOOT  to 
run  with  the  CompuPro  Interfacer  4  1/0 
board  but  would  appreciate  the  code  if 
somebody  else  has  already  completed  it. 
Finally,  he  suggests  that  a  control-P  trap 
be  implemented  to  enable  online  printing 
of  everything  that  goes  across  the  line. 

CP/M  Plus  Feedback 

Victor  Ung,  of  Monterey  Park,  Cali¬ 
fornia,  writes  about  his  experiences  on 
implementing  CP/ M  Plus: 

“The  following  is  intended  to  be  of 
assistance  to  those  who  are  trying  to 
generate  a  CP/M  Plus  system.  These  tips 
apply  if  you  are  writing  a  BIOS  from 
scratch  as  outlined  in  the  CP/M  Plus  •Sys¬ 
tem  Guide.  I  assume  that  you  have  pur¬ 
chased  a  generic  system  and  that  you 
have  thoroughly  read  the  documentation. 

“Z80  macros  versus  the  real  thing.  I 
don’t  understand  why  people  can’t  pro¬ 
gram  a  Z80  without  inventing  their  own 
opcodes.  If  you  wish,  you  can  use  Micro¬ 
soft’s  MACRO-80  assembler  to  generate 
,REL  files  instead  of  using  the  Z80.LIB 
macros  supplied  with  RMAC. 

“Most  of  the  problems  I  had  with 
the  CPMLDR  were  because  of  the  System 
Guide’s  simple  understatement  that  ‘the 
(CPMLDR)  LDRBIOS  is  essentially  a  non- 
banked  (CP/M  Plus)  BIOS.’  This  prompted 
me  at  first  to  try  to  link  my  nonbanked 
version  of  BIOS3  with  CPMLDR. REL 
which  led  me  to  diagnose  the  following 
problems: 

“When  CPMLDR  calls  the  BOOT 
routine  of  LDRBIOS,  it  does  so  with  a 
small  eight-level  stack.  Only  three  levels 


are  left  before  the  delimiter  of  the  still 
undisplayed  sign-on  message  is  overlaid.  If 
the  BOOT  routine  overflows  the  stack, 
CPMLDR  will  not  only  display  the  DR1 
copyright  but  will  also  treat  you  to  an 
ASCII  memory  dump  of  your  system. 

“CPMLDR  needs  a  non-relocatable 
SCB.  In  LDRBIOS  you  should  define  the 
SCB  as  an  absolute  block  of  storage. 
Otherwise  the  SCB  will  be  located  at 
FEOOH,  where  it  will  be  overlaid  as 
CPM3.SYS  is  loaded. 

“There  is  no  automatic  disk  buffer 
allocation  in  CPMLDR.  You  must  define 
all  values  for  the  DPH  and  DPB  of  the 
drive  used  to  load  the  system.  A  directory, 
DIRBCB,  and  data  buffer,  DATABCB, 
must  also  be  al  ocated. 

“The  CP/M  BIOS  is  where  the 
improved  sysgen  documentation  really 
shines.  Everything  you  need  to  know 
about  your  new  BIOS  is  in  the  System 
Guide.  However,  if  you  are  trying  to 
generate  a  banked  version  of  BI0S3,  re¬ 
ferred  to  as  BNKBIOS3,  then  you  should 
carefully  read  section  3.5  on  ‘Banking 
Considerations.’ 

“A  possible  RMAC  bug  may  exist  if 
you  use  the  CPM3.LIB  macro  library  to 
define  large  drive  characteristics.  While  I 
am  not  ready  to  cry  BUG!  yet,  I  have  had 
some  problems  using  the  DPB  macro  to 
define  large  (over  5MB)  drives.  Carefully 
examine  the  PRN  output  file  and  if  you 
notice  wrong  values  for  DSM,  DRM,  and 
CKS,  then  you  should  give  up  and  manu¬ 
ally  calculate  and  code  the  proper  DPB 
values. 

“It  is  well  worth  the  effort  to  write 
a  new  BIOS  from  the  ground  up  rather 
than  to  hack  up  an  existing  CP/M  2.2 
BIOS.  It  took  me  about  30  hours  to  get  a 
nonbanked  system  up  and  another  four 
hours  to  convert  it  to  a  banked  system. 
The  chapter  on  how  to  debug  the  BIOS  is 
excellent  and  I  had  no  problem  under¬ 
standing  my  mistakes.  DRI  could,  how¬ 
ever,  improve  section  5.2  on  ‘Customizing 
the  CPMLDR.’  ” 

Searching  Further 

Several  months  ago  I  asked  for  help 
in  locating  a  CCP  patch  that  will  search 
user  area  0  for  a  .COM  file  not  found  in 
the  current  user  area.  Ernest  Payne,  of 
Tucson,  Arizona,  responded  in  grand 
style.  He  sent  along  a  complete  disassem¬ 
bler  source  listing  of  the  CCP  and  BDOS 
for  CP/M  2.2.  He  also  pointed  me  to  an 
article  in  the  March/April  1982  issue  of 
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;  From 

DDJ 

Oct  '82  page 

47 

;  To  s  e  r  v  e 

as  simple  terminal/modem  program.... 

/ 

;  First,  my 

equates  ( DLD) 

9 

false 

equ 

0 

true 

equ 

not  false 

s  tdcpm 

equ 

true 

ex  i  tchr 

equ 

05h 

e  sc 

equ 

lbh 

f astclk 

equ 

true  ; 

work  with  6Mhz  clock 

9 

modctlp 

equ 

4dh 

modem  control  port 

modsndb 

equ 

20h 

my  bit  to  test  to  send 

modsndr 

equ 

20h 

my  bit  to  say  ready  to  send 

mod  r cvb 

equ 

01h 

my  bit  to  test  to  receive 

modr cvr 

equ 

0  lh 

my  value  when  ready  to  rcvr 

moddatp 

equ 

48h 

my  modem  data  port 

9 

er rl  im 

equ 

10 

soh 

equ 

1 

288 

if 

f astclk 

289 

mov 

a  ,b 

290 

add 

a 

291 

;  now 

for  6Mhz  clock 

292 

add 

b 

this  statement  added  for  6Mhz 

293 

mov 

b ,  a 

294 

end  i  f 

329 

330 

;  initialization  for  Morrow  MULT/10  board 

331 

base 

equ 

48h 

basic  port  address 

332 

ini tmod 

mv  i 

a ,  2 

group  select  (ACE  #2) 

333 

out 

base+7 

output  it 

334 

mv  i 

a, 135 

set  DLAB ,  8  bit  data,  2  stop 

335 

out 

based-  3 

output  that 

336 

mv  i 

a  ,8 0h 

low  byte  BAUD  RATE 

337 

out 

base 

output  that 

338 

mv  i 

a  ,1 

high  byte  BAUD  RATE 

339 

out 

base+1 

output  that  for  300  BAUD 

340 

mv  i 

a, 7 

clear  DLAB 

341 

out 

base+3 

output  to  line  control  register 

342 

xr  a 

a 

clear  A 

343 

out 

base+5 

clear  data  available  flag 

344 

mv  i 

a  ,0 

disable  interrupts 

345 

out 

based- 1 

output  that 

346 

9 

347 

mv  i 

a, 2 

be  sure  group  select  is  2 

348 

out 

based-7 

output  that 

349 

mv  i 

a, 7 

be  sure  DLAB  is  low 

350 

out 

based-3 

output  that,  and  that's  all. 

351 

9 

352 

ret 

Figure  1. 

MBOOT  Update  for  Morrow  MULT/IO  Board 
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Microsystems  magazine  which  contains 
the  necessary  BIOS  changes  to  imple¬ 
ment  this  enhancement.  If  you  don’t 
have  access  to  this  issue,  send  me  a 
SASE  and  I  will  return  a  copy  of  it  to 
you. 

If  you  don’t  have  access  to  the  BIOS 
source  code  for  your  system,  or  you  want 


to  go  beyond  this  one  change,  a  complete 
Z80  CCP  replacement  is  available  from 
SIG/M.  I  have  been  using  the  original  ver¬ 
sion  of  ZCPR  for  over  a  year  now  and 
have  become  so  accustomed  to  its  extra 
features  that  I  have  a  difficult  time  using 
the  standard  version  of  CP/ M’s  CCP.  The 
latest  version  of  ZCPR  (ZCPR2)  is  con¬ 


tained  on  SIG/M  volumes  98  through  107. 
No,  I  didn’t  make  a  mistake;  it  takes  ten 
8”  disks  to  hold  all  the  source  code  and 
documentation  plus  a  few  other  goodies. 
For  a  brief  description  of  ZCPR’s  non¬ 
standard  functions,  consult  Figure  2 
(below  left).  SIG/M  can  be  reached  at 
Box  97,  Iselin,  New  Jersey  08830. 

Take  note  of  one  problem  before 
modifying  your  BIOS  or  implementing 
ZCPR.  Multiple-phase  programs  such  as 
WordStar  or  dBase  II  that  load  overlays  at 
run  time  may  not  always  execute  proper¬ 
ly.  Once  the  CCP  has  loaded  the  program 
from  the  proper  user  area  and  turned  con¬ 
trol  over  to  it,  the  application  program  is 
unaware  of  which  user  area  contains  its 
overlay  segments.  No  easily  implemented 
solution  for  this  inadequacy  is  available. 
The  only  sure  way  to  avoid  problems  of 
this  type  is  to  restrict  yourself  to  one  user 
area  or  to  copy  multi-phase  programs 
into  all  user  areas  where  they  will  be 
used. 

64K  and  Beyond 

Memory  management  techniques  have 
been  in  use  for  years  on  large  computers. 
Their  reason  for  existence  is  to  expand 
the  number  of  uniquely  addressable 
memory  positions  beyond  the  limitations 
imposed  by  the  cpu.  8080  and  Z80 
processors  provide  16  address  bits,  there¬ 
by  limiting  the  maximum  number  of 
directly  addressable  positions  to  65,536. 
64K  of  memory  may  seem  adequate 
considering  that  only  a  few  years  ago 
most  micros  were  operating  with  16K. 
But  as  programs  become  more  sophisti¬ 
cated  ,  their  appetite  for  memory  increases. 
For  example,  one  of  the  more  popular 
spreadsheet  programs  provides  13K  of 
free  memory  in  a  64K  CP/M  system.  Un¬ 
fortunately  this  equates  to  only  several 
hundred  active  cell  positions  —  barely 
adequate  for  any  type  of  serious  financial 
modeling.  Adding  4K  to  6K  of  memory 
expands  the  maximum  sheet  size  to  the 
point  of  overtaxing  a  4MHz  Z80. 

Going  beyond  64K  requires  addi¬ 
tional  hardware  that  automatically  inserts 
extra  high -order  address  bits  when  a 
memory  transfer  takes  place.  Most  of  the 
the  S-100  cpu  and  memory  boards  being 
manufactured  today  contain  additional 
logic  for  this  purpose. 

In  order  to  understand  how  extended 
address  systems  work,  visualize  one  16K 
fixed  segment  of  memory  with  a  base  ad¬ 
dress  of  C000H  and  several  48 K  segments 
of  memory  each  with  a  common  base 
address  of  0000H.  All  memory  segments 
will  respond  to  the  normal  16  bits  of  ad¬ 
dress  information  presented  by  the  cpu. 
Additionally,  each  48K  banked  memory 
segment  will  also  respond  to  8  bits  of  ex¬ 
tended  address  information.  When  a  mem¬ 
ory  transfer  is  to  take  place  on  the  bus, 
the  cpu  puts  out  its  16  bits  of  address 
information  to  select  one  byte  position 


(A)  Z80  code  is  used  throughout  to  reduce  the  size  of  the  CCP  and  give  room 
to  implement  the  additional  functions.  Also,  the  input  line  buffer  has 
been  reduced  in  size  to  approximately  8 OH  bytes. 

(B)  A  new  Command-Search  hierarchy  has  been  implemented: 

1 .  Scan  the  list  of  built-in  CCP  commands. 

2.  If  the  command  is  not  CCP-resident,  look  for  a  .COM  file  on  the  cur¬ 
rent  disk  in  the  current  user  area. 

3.  If  the  .COM  file  is  not  found  in  the  current  user  area  and  the  current 
user  area  is  not  the  default  user  area  (normally  0),  then  the  default 
user  area  is  selected  and  scanned  for  the  file. 

4.  If  the  .COM  file  is  not  found  on  the  currently  logged  drive,  drive  A:  is 
selected  and  scanned  for  the  file  under  the  default  user  area. 

(C)  The  default  user  number  can  be  changed  by  the  DFU  command. 

(D)  A  new  command  called  PAGE  will  output  a  file  to  the  CON :  device  one 
screen-full  at  a  time  and  wait  for  a  continue  character.  Otherwise,  it  is 
like  TYPE. 

(E)  The  new  LIST  command  sends  a  file  to  the  LST:  device. 

(F)  The  CLS  command  clears  the  terminal  screen. 

(G)  The  user  number  is  printed  as  part  of  the  command  prompt;  the  prompt 
is  now  du>  (e.g.,  “A0>”  or  “A15>”). 

(H)  The  ERA  command  now  displays  the  names  of  all  the  files  it  has  erased. 

(I)  The  DIR  command  has  the  additional  special  form  “DIRA”  which  dis¬ 
plays  all  files  (both  non-system  and  system),  while  “DIR”  displays  just 
the  non-system  files. 

(J)  The  directory  display  no  longer  displays  the  disk  name  at  the  beginning 
of  each  line  and  it  now  includes  a  “ .  ”  between  the  file  name  and  file 
type  (e.g.,  FILE.TYP). 

(K)  The  SUBMIT  File  Facility  now  expects  the  $$$.SUB  file  to  be  on  the 
currently  logged -in  disk  (as  opposed  to  always  A: ). 

(L)  The  command  line  prompt  is  now  “=”  if  the  command  comes  from  a 
$$$.SUB  file  and  “>  ”  if  the  command  comes  from  the  user.  Also,  the 
“>  ”  is  not  printed  until  all  preprocessing  is  completed. 

(M)  A  form  feed  is  sent  to  the  LST :  device  by  the  FF  command. 

(N)  The  new  LF  command  sends  a  variable  number  of  line  feeds  to  the  LST: 
device. 

(O)  All  CCP  commands  (such  as  SAVE),  which  normally  take  a  decimal  num¬ 
ber,  now  will  also  accept  hex  numbers  (e.g.,  20H). 

(P)  The  new  SAVS  command  is  like  SAVE  except  that  it  saves  a  number  of 
disk  sectors. 

(Q)  A  pair  of  commands  have  been  added  to  allow  loading  a  file  anywhere  in 
memory  (GET)  and  then  executing  it  (JUMP  xxx).  Of  course,  JUMP 
could  also  execute  a  PROM  program.  GET  prevents  a  file  from  over¬ 
writing  BDOS  or  BIOS. 

(R)  A  “GO”  command  has  been  added  which  does  an  immediate  jump  to 
100H. 

(S)  Doing  a  warm  boot  now  maintains  the  current  user  and  drive  numbers 
even  when  recovering  from  an  I/O  error. 

(T)  The  HELP  command  displays  a  list  of  the  resident  commands. 

Figure  2. 

ZCPR  Non-Standard  Functions 
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within  one  of  the  48K  segments.  At  the 
same  time,  the  extended  address  logic 
asserts  its  8  bits  of  extended  address  infor¬ 
mation  to  select  one  of  the  48K  banked 
segments.  Hence,  one  byte  within  one  of 
the  48 K  segments  is  selected.  Reviewing 
Figure  3  (at  right)  at  this  time  may  be 
helpful. 

Two  basic  types  of  memory  expan¬ 
sion  are  employed  today.  Conceptually 
they  are  the  same;  their  difference  exists 
in  how  they  are  implemented.  The  oldest 
method,  Cromemco  standard,  requires 
that  each  memory  board  have  an  I/O  port 
at  address  40H  to  receive  a  one-byte 
selection  code,  and  some  form  of  static 
switch  to  preset  a  unique  bit  pattern  used 
as  the  extended  address.  A  simple  output 
instruction  to  port  40H  will  then  enable 
the  memory  bank  with  the  matching  pre¬ 
selected  bit  pattern  and  disable  all  others. 
The  newest  method,  IEEE-696  S-100 
bus  standard,  sets  aside  8  extra  bus  ad¬ 
dress  lines  for  use  as  an  extended  address. 
When  used  in  conjunction  with  the  noi 
mal  1 6  address  lines,  this  effectively  pro¬ 
vides  a  24-bit  address.  Each  memory 
board  in  this  type  of  system  must  have 
enough  on-board  selection  logic  to  prop¬ 
erly  respond  to  all  24  bits  of  address  for 
any  memory  transfer.  The  drivers  for 
these  8  extended  address  lines  are  usually 
a  feature  of  the  cpu  board.  Again,  only 
one  output  instruction  is  needed  to  select 
the  desired  banked  memory  segment. 

Some  software  coordination  is  also 
necessary  to  allow  this  type  of  system  to 
operate  properly.  Any  information  trans¬ 
fer  between  memory  banks  must  be  passed 
through  the  fixed,  or  common,  bank  of 
memory  because  only  one  bank  can  be 
enabled  at  a  time.  This  task  is  usually 
delegated  to  a  special  subroutine  of 
CP/M’s  BIOS. 


COMMON  BANK  I  Base 

- 1  Address  C000H 


I  BANK  2  ) 


I  I  Extended  Base 

I  BANK  1  j - Address  02H  Address  0000H 


I  I  Extended  Base 

BANK  0  1 - Address  01H  Address  0000H 


Extended  Base 

Address  00H  Address  0000H 


B  0 - II  I  I 

U  I  II 

S  I  II 

7 - 1  |  | 

I  I 

M  A  0 - 1  I 

E  D  I 

M  D  | 

0  R  | 

R  E  | 

Y  S  I 

S  15 - 1 

Figure  3. 

Extended  Bank  Selection  Memory  Model 


I  think  you  will  agree  that,  once  some 
of  the  basic  principles  of  bank  selection 
are  understood,  CP/M  Plus’s  operation 
will  become  more  readily  apparent.  Next 
month  I  will  continue  with  a  wrap-up  of 
CP/M  Plus’s  features.  In  following  months 
I  will  be  discussing  the  steps  necessary  to 
bring  CP/M  Plus  up  and  any  problems 
that  I  encounter.  I’m  looking  forward  to 
this  adventure  because  1  purchased  a 
256K  dynamic  memory  board  just  so  I 
can  put  all  the  new  features  to  use.  SBj 
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16-BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


MS-DOS  Rebuttal 

Tim  Paterson,  the  author  of  MS-DOS 
1.0  and  currently  director  of  engineering 
at  Seattle  Computer,  wrote  in  to  respond 
to  some  of  my  comments  about  PC-DOS 
in  the  May  1983  column.  The  following 
paragraphs  are  taken  verbatim  from  the 
body  of  his  letter: 

“Neither  CP/M-86  nor  MS-DOS 
check  if  a  disk  has  been  changed  when  a 
file  is  read  or  written  —  only  when  it  is 
opened  or  closed.  Such  a  test  would  be 
totally  impractical.  In  the  CP/M-86  case, 
files  are  written  128  bytes  at  a  time  by 
making  successive  calls  to  the  operating 
system.  To  test  for  a  changed  disk  would 
require  a  read  of  the  disk  directory  before 
writing  each  sector.  If  the  test  is  to  be 
made  at  all,  it  must  be  made  on  every 
‘write  sector’  system  call,  since  the  oper¬ 
ating  system  has  no  way  to  know  when  it 
needs  to  check  and  when  it  doesn’t.  The 
extra  overhead  involved  with  seek  time, 
latency  delays,  and  reading  from  the  direc¬ 
tory  would  increase  the  time  to  write  a 
file  by  at  least  an  order  of  magnitude. 

“The  way  both  operating  systems 
work  is  like  this:  Both  CP/M-86  and 
MS-DOS  keep  a  map  in  memory  of  avail¬ 
able  disk  space.  Each  entry  in  the  map 
corresponds  to  a  chunk  of  free  space  of 
fixed  size,  such  as  1  Kbyte.  As  more  space 
is  needed  to  extend  a  file,  the  map  is 
searched  for  free  space  to  be  assigned  to 
the  file.  That  new  chunk  of  space  is  then 
written  to  as  required  for  the  file.  If  the 
disk  has  been  changed  since  the  file  was 
opened,  the  map  of  free  space  will  be  in¬ 
correct,  and  the  data  in  another  file  may 
get  destroyed  at  this  point. 

“When  the  file  is  closed,  the  two  sys¬ 
tems  diverge  only  slightly.  CP/M-86  per¬ 
forms  a  checksum  of  the  directory,  which 
it  compares  with  a  stored  value  from  a 
previous  checksum.  If  the  checksum  dif¬ 
fers,  the  disk  is  marked  ‘read-only’  and 
the  close  fails.  MS-DOS  searches  for  the 
file  in  the  directory  and,  if  found,  com¬ 
pares  its  position  in  the  directory  with 
its  position  when  it  was  opened,  which  is 
stored  in  the  File  Control  Block.  If  these 
do  not  match,  the  close  fails  and  internal 
buffers  (including  the  free  space  map)  are 
invalidated. 

“Of  course,  it  is  critical  that  the  map 
of  free  space  in  memory  be  kept  up  to 
date  as  disks  are  changed.  CP/M-86  will 
only  update  its  map  when  the  operator 
types  control- C,  or  with  a  ‘disk  reset’ 
system  call,  even  if  it  has  detected  a  disk 
change.  MS-DOS  updates  its  map  from 
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the  disk  every  time  a  file  is  opened,  unless 
another  file  is  still  in  the  process  of  being 
written. 

“MS-DOS  allows  disks  to  be  changed 
whenever  files  are  not  open  for  writing. 
If  application  programs  kept  this  to  a 
minimum,  then  MS-DOS  could  be  nearly 
bullet-proof.  The  rule  that  should  be 
used  is  that  whenever  a  program  is  going 
to  wait  for  user  input,  it  should  close  out¬ 
put  files,  then  re-open  them  later  (with 
corresponding  disk  check  change)  if  writ¬ 
ing  is  to  continue.  Thus  the  user  sees  that 
any  time  the  computer  stops  to  wait  for 
him,  he  can  change  disks. 

“The  MS-DOS  editor  EDLIN  makes 
the  serious  mistake  of  leaving  the  file 
open  for  writing  during  the  editing  proc¬ 
ess.  When  I  wrote  EDLIN  (in  the  summer 
of  1980),  it  never  occurred  to  me  that 
people  would  swap  disks  while  editing.  It 
must  happen,  I  suppose,  when  someone 
gets  so  distracted  that  they  forget  what 
they  are  doing.  Unfortunately,  I’m  afraid 
EDLIN  is  not  the  only  program  leaving 
output  files  open;  I  suspect  this  is  com¬ 
mon  to  many  other  editors,  and  other 
programs  as  well. 

“I  tested  what  happens  when  disks 
are  swapped  within  EDLIN,  to  prove  for 
myself  that  it  works  the  way  I  wrote  it.  I 
edited  a  small  (7K)  file,  but  swapped 
disks  before  ending  the  session.  EDLIN 
gave  no  indication  of  an  error.  Using  DIR 
and  CHKDSK  commands,  the  disk  I 
swapped  in  appeared  to  be  unchanged.  I 
typed  several  of  the  files  from  the  disk, 
and  they  were  unharmed.  7K  of  data 
must  have  been  written  somewhere  on 
the  disk,  but  I  couldn’t  find  it.  It  might 
well  have  been  written  in  the  disk’s  free 
space. 

“In  summary,  CP/M-86  does  not 
‘carefully  protect’  the  integrity  of  files 
on  a  disk  that  has  been  changed  at  the 
wrong  time.  Nor  is  the  behavior  of  MS- 
DOS  ‘inexcusable,’  since  it  is  nearly  the 
same  as  CP/M-86.  For  a  given  application 
program,  both  operating  systems  are 
about  equally  susceptible  to  destroying 
data  on  a  disk  that  has  been  swapped  in 
at  the  wrong  time.” 

I  am  grateful  to  Mr.  Paterson  for  tak¬ 
ing  the  time  to  send  this  explanation,  and 
I  was  certainly  in  error  in  stating  that 
CP/M-86  will  not  allow  data  to  be  written 
into  the  wrong  place  on  an  improperly 
swapped  disk.  But  his  letter  leaves  several 
questions  unanswered. 


First,  the  test  of  EDLIN  was  not  very 
exhaustive.  Presumably,  when  the  editing 
session  was  ended,  MS-DOS  was  still 
working  from  the  previous  disk’s  alloca¬ 
tion  map  —  so  the  fact  that  it  did  not 
write  the  7K  edited  file  over  some  other 
file’s  data  on  the  new  disk  was  purely 
good  luck.  Next,  if  MS-DOS  was  working 
properly,  it  should  have  returned  a  failure 
code  to  EDLIN  when  the  file  was  closed, 
since  the  disk  had  been  improperly 
swapped.  Either  EDLIN  didn’t  get  the 
error  code  or  it  didn’t  bother  to  report 
it  —  but  which? 

Finally,  even  if  it  is  unclear  just  how 
it  occurs,  PC-DOS  has  definitely  been 
observed  on  rare  occasions  to  clobber  the 
directory  of  a  disk  that  was  improperly 
swapped  in  while  a  file  was  open  for  write. 
Although  this  happened  to  me  several 
times  soon  after  I  bought  my  IBM  PC,  I 
have  not  encountered  it  recently.  (Was 
it  a  subtle  bug  in  PC-DOS  version  1.0  that 
was  eliminated  in  1.1;  did  I  just  uncon¬ 
sciously  learn  to  avoid  situations  that 
caused  it;  or  did  it  require  some  fairly 
unusual  combination  of  circumstances 
that  by  coincidence  hasn’t  recurred? 

Attempts  to  recreate  such  an  error 
intentionally  have  been  unsuccessful  so 
far;  but,  from  the  description  provided  by 
Mr.  Paterson,  at  least  one  window  to  such 
an  event  seems  to  be  open.  If  the  swapped 
disk  happened  to  have  a  file  by  the  same 
name  in  the  same  directory  position  as 
the  file  that  was  opened  for  write  on  the 
previous  disk,  would  PC-DOS  recognize 
that  the  disk  had  been  changed,  or  go 
ahead  and  write  the  old  disk’s  allocation 
map  and  directory  entry  onto  the  new 
disk?  Further  input  from  readers  and 
from  Mr.  Paterson  on  this  subject  is 
welcomed. 

68000  Tools 

Steve  Passe,  of  Englewood,  Colorado, 
sent  in  a  pair  of  68000  subroutines  (see 
Listings  1  and  2,  pages  94-98)  and  wrote: 
“This  is  the  first  submission  of  what  I 
hope  will  be  a  long  string  of  68K  tool 
donations  on  my  part.  I  decided  to  start 
by  converting  your  first  two  8086  tools 
(ascbin  and  binasc),  and  tried  to  stick  to 
the  format  of  the  originals  as  much  as 
possible.  I  made  them  take  full  advantage 
of  the  32-bit  word  size  of  the  68000; 
thus,  the  legal  range  for  both  routines  is 
+  2,147,483,647  through  -2,147,483,648. 
This  made  them  a  little  longer  than  their 
8086  counterparts  as  overflow  and  carry 
conditions  had  to  be  taken  into  account. 
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“I  operate  a  BBS  type  service  which 
I  encourage  people  interested  in  the  68000 
series  chips  to  call.  The  board  is  primarily 
dedicated  to  the  C  programming  language, 
but  I  will  soon  be  setting  aside  space  in 
the  file  system  for  68000  public  domain 
code  also.  There  is  also  a  ‘room’  in  the 
bulletin  board  system  dedicated  to  info/ 
discussion  of  the  68K.  Inform  me  if  and 
when  these  routines  are  to  be  published 
and  I  will  make  sure  that  the  code  for 
them  is  online  by  that  time.  The  BBS 
is  up  24  hours,  7  days  a  week  at  (303) 
781-4937.” 


Sizing  Memory  on  the  IBM  PC 

Those  of  you  with  really  big  applica¬ 
tions  programs  on  the  IBM  PC  will  have 
noticed  that  the  maximum  memory  size 
that  can  be  set  on  the  machine’s  sense 
switches  is  544  Kbytes,  even  though  ac¬ 
cording  to  the  published  memory  map, 
you  can  add  contiguous  RAM  at  least  to 
A0000H  (655K).  The  sense  switches  are 
only  examined  by  the  initialization  soft¬ 
ware  when  the  machine  is  turned  on,  and 
the  result  is  stored  into  a  dedicated  mem¬ 
ory  location  that  is  referenced  by  the 
operating  system  thereafter. 

Rick  Wilton  has  donated  a  short  util¬ 
ity  program  called  MEMS1ZE  that  can  be 
added  to  your  AUTOEXEC.BAT  file  to 
physically  size  RAM  and  reset  the  operat¬ 
ing  system’s  dedicated  variable  to  reflect 
the  true  amount  of  memory.  When  MEM- 
SIZE  is  invoked,  it  first  checks  to  see  if 
the  sense  switches  were  set  for  less  than 
544  Kbytes  —  if  so,  it  simply  exits.  This 
is  to  protect  users  who  have  large  amounts 
of  memory  but  are  using  it  for  an  “elec¬ 
tronic  disk”  instead  of  making  it  directly 
available  to  applications  programs. 

If  the  sense  switches  are  indeed  set 
for  the  maximum,  MEMSIZE  attempts 
a  write/read  cycle  to  memory  on  each 
paragraph  boundary  up  to  the  address 
A0000H,  which  is  defined  as  the  begin¬ 
ning  of  “reserved  memory”  by  the  IBM 
Technical  Manual.  It  shifts  the  highest 
segment  address  off  to  the  right  to  find 
the  amount  of  Kbytes,  then  stores  that 
value  into  the  memory  size  variable. 
MEMSIZE  is  provided  as  Listing  3  (page 
99),  which  is  in  a  form  compatible  with 
the  Microsoft  Macro  Assembler. 
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16-Bit  Toolbox 

Listing  One  (Text  begins  on  page  92) 


Convert  3£  bit  signed  binary  #  to  ascii  string 
3/13/83  Steve  Passe 


************ ************************************************************* 
*  * 
* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 


al 

dl 

dl 
d£ 
a  1 


pointer  to  8  byte  buffer  to 
hold  string. 

32  bit  signed  number. 


* 
* 
* 
* 
* 
* 

(same  as  call  value)  * 

digitsinstring.  * 

address  of  first  char  in  string.  * 

* 

************************************************************************* 


Called  values: 


Returned  values: 


org  *880 


binary_tc<_asci  i 


rnovern.  1 

dl /d3/d4, - ( sp 

rnoveq 

#1 1-1, d£ 

init_buf 

move. b 

#’  (al)  + 

dbf 

d£, init  buf 

moved 

#0,  d£ 

tst.  1 

dl 

bpl .  s 

div  Iood 

neg.  1 

dl 

div_loop 

di  vu 

#10, dl 

* 

bvs.  s 

overflow 

move. 1 

dl,  d3 

and.  1 

#*0000ffff, dl 

bra.  s 

make_asci i 

overflow 

move. w 

d  1 .  d3 

clr.  w 

dl 

5WSD 

dl 

d  i  vu 

#10. dl 

move. w 

dl,  d4 

move. w 

d3,  d  1 

d  i  vu 

#10, dl 

move.  1 

d  1 ,  d3 

swap 

dl 

move,  w 

d4,  dl 

swap 

dl 

* 

make_asci i 

swap 

d3 

add.  b 

#’  0’  ,  d3 

buffer  length  minus  dbf 
space  into  buffer 
more. . . 

clear  char  count 
is  it 
neg? 

make  oosative  for  now 
strip  digit  from  right 

overflow  flag  set? 
d3  ->  remainder/xxx 
erase  remainder 
skio  overflow  stuff 

prepare  for  double  div 

zero  low  word 

high  word  into  low 

divide  high  word 

save  Quotient 

low  word  into  low 

divide  low  word 

d3  ->  remainder 

R/Q  ->  Q/R 

dl  ->  L/H 

dl  ->  H/L 

remainder  into  low  word 
make  ascii  (Continued  on  page  96) 
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16-Bit  Toolbox 

Listing  One  (Listing  continued,  text  begins  on  page  92) 


move. b 
addq. b 
tst .  1 
brie,  s 


d3, - <al ) 
#1,  d£ 
dl 

div  loco 


movern. 1  (sd )  +  ,  d  1  /d3/d4 


tst .  1 
bpl .  s 
move. b 
addq. b 


dl 

all  _dorie 
#’  ,  -  < a  1 ) 

#1,  d£ 


fill  buffer  from  right 
inc  count 
gone  zero  yet? 

no.  .  . 

restore  call  val,  work  reg. 
was  it  negative? 
no 

add  the  ’  — ’ 
inc  count 


all  done 


Listing  Two 


End  Listing  One 


************************************************************************* 
#  * 

*  Convert  ascii  string  to  binary  value  * 

*  3/1/03  Steve  Passe  * 


Called  values: 


al  ==  pointer  to  ascii  string  reo.  of 
decimal  number.  Legal  string 
chars:  +-. 01 £3456789 


*  Skips  leading  blanks,  terminating  on  first  illegal  char.  * 

*  * 

*  Returned  values:  dl  ==  signed  binary  result  * 

*  d£  ==  digits  after  decimal  point,  * 

*  al  ==  address  of  first  illegal  char.  * 

*  * 
************************************************************************* 


ski p_si gn 
convert 


digit 


*800 


asci i_to_binary 


ski p_ws 


movern. 1 

d3-d4,  - <sp) 

save  registers 

rnoveq 

#0,  dl 

clear  answer 

moveq 

#-l, d£ 

no  decimal  to  start 

crnp.  b 

#’  ’ ,  (al >  + 

look  for  space. . . 

beq.  s 

ski p_ws 

sk i  p  on.  .  . 

move,  b 

- (al )  ,  - (sp) 

save  (possible)  sign 

crnp.  b 

#’ +* ,  (al ) 

look  for  pos.  sign 

bea.  s 

skip  sign 

skip  sign 

crnp.  b 

#’  ,  (al  ) 

look  for  neg.  sign 

brie,  s 

convert 

ready  for  first  char 

addq 

#1,  al 

inc  string  pointer 

move,  b 

< a  1 )  +,  d3 

into  data  reg 

crnp.  b 

#’  .  »  ,  d3 

look  for  decimal  point 

brie,  s 

d  i  d  it 

nope 

rnovea 

#0,  d£ 

clear  count 

bra.  s 

convert 

continue  digit  search 

crnp.  b 

#’  0’  ,  d3 

low  end  numeral 

bcs 

scan  done 

1 ess  than  ’  0’ 

crnp.  b 

#’ 9’ , d3 

high  end 

bh  i 

scan  done 

greater  than  ’9’ 

and.  1 

#*0f, d3 

make  binary 

(Continued  on  page  98) 
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16-Bit  Toolbox 

Listing  Two  (Listing  continued,  text  begins  on  page  92) 


scan  done 


not_neg 


move.  1 

dl ,  d4 

get  high  word.  . . 

swap 

d4 

...  into  low  word 

m  u  1  li 

#10, dl 

previous  count,  low 

m  u  1  u 

#10, d4 

high  word  also 

swap 

dl 

high  word  into  low, 

add .  w 

d4,  d  1 

add  high  to  d4/lc>w 

swap 

dl 

restore  order 

add.  1 

d3,  dl 

add  new  digit 

tst 

d£ 

past  decimal? 

brn  i .  s 

convert 

not  yet 

addq. b 

#1,  d£ 

yes,  one  more  past 

bra.  s 

convert 

again 

suba.  1 

#1,  al 

align  on  first  fail 

move,  b 

<sp) +, d3 

get  sign 

crnp.  b 

#’  ,  d3 

was  it  neg? 

bne.  s 

not  neg 

no.  .  . 

neg.  1 

dl 

yes. . . 

movern.  1 

(sp)+, d3-d4 

restore  work  registi 

rts 

end 

End  Listing  Two 
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16-Bit  Toolbox 

Listing  Three 


naae  aeasize 
page  55,132 

title  ’HENS1ZE  --  reset  PC/DOS  aeaory  size  variable 


HENSIZE  —  reset  PC/DOS  aeaory  size  variable  at  location  40:13h 
(  for  IBM  PC  under  PC-DOS  1.1  —  See  Technical  Reference  p.  A-2  ) 
Version  1  April  1983 

Richard  Hilton 
Laboratory  Hicrosysteas 
4147  Beethoven  Street 
Los  Angeles,  CA  90066 


0000 

cseg 

segaent  byte 

assume 

cs:cseg,ds:c5eg 

0100 

org 

lOOh 

0100 

BB  0040 

start: 

BOV 

bx,40h 

t 

set  D5: BX  to  point  ... 

0103 

8E  DB 

•ov 

ds,bx 

0105 

BB  0013 

•ov 

bx,13h 

1 

...  to  aeaory  size  variable 

0108 

81  3F  0220 

c«p 

word  ptr  tbx],220h  j  is  current  aea  size  <  544K  ? 

010C 

7C  28 

jl 

exitl 

1 

exit  if  it  is 

010E 

B8  8300 

AOV 

ax,8800h 

> 

otherwise,  set  up  test  loop 

0111 

BB  0000 

BOV 

bx  ,0 

0114 

30  A000 

loopl: 

ctp 

ax,0a000h 

• 

1 

is  AX  =  beginning  of  "reserved" 

0117 

74  OF 

je 

exit2 

• 

1 

yes,  so  exit 

0119 

8E  08 

•ov 

ds,ax 

• 

» 

no,  so  use  this  as  a  segaent 

01  IB 

89  07 

BOV 

lbxl,ax 

5 

write  contents  of  AX  to  OS: BX  .. 

0110 

8B  OF 

BOV 

cx,lbxl 

5 

...  and  read  it  back  to  CX 

01  IF 

3B  Cl 

CBp 

ax,cx 

5 

does  data  read  =  data  written  ? 

0121 

75  05 

jne 

ex  i  t2 

5 

exit  if  it  doesn’t 

0123 

8C  08 

AOV 

ax,ds 

5 

otherwise,  copy  OS  to  AX  ... 

0125 

40 

inc 

ax 

i 

...  increaent  it  ... 

0126 

EB  EC 

j*p 

loopl 

• 

j 

...  and  loop 

0128 

B1  06 

ex  it 2: 

BOV 

cl, 6 

i 

nucber  of  bits  to  shift 

012A 

03  E8 

shr 

ax, cl 

i 

convert  segaent  to  Kbytes 

012C 

BB  0040 

BOV 

bx,40h 

) 

again,  set  DS: BX  ... 

012F 

BE  0B 

•OV 

ds,bx 

) 

...to  point  to  aeaory  size  vari 

0131 

BB  0013 

BOV 

bx , 1 3h 

0134 

89  07 

BOV 

lbxl,ax 

i 

store  updated  aeaory  size 

0136 

CD  20 

exit!: 

int 

20h 

• 

i 

exit  to  DOS 

0138 

cseg 

ends 

5 

end  of  code  segaent 

end 

start 

5 

end  of  asseably  —  start  addr  at 
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OF  INTEREST 


by  Michael  Wiesenberg 

Cachet  for  a  Chameleon 

The  Chameleon,  by  Seequa,  an 
IBM  PC-compatible  dual  processor 
(8088  and  Z80A)  portable  computer, 
has  been  added  to  the  General  Services 
Administration’s  (GSA)  “Authorized 
ADP  Schedule  for  Microcomputers, 
Peripherals  and  Support  Equipment.” 
This  is  tantamount  to  pre-approval  of 
purchases  of  a  product  because  govern¬ 
ment  agencies  can  buy  products  from 
the  list  as  needed,  without  having  to 
go  through  a  bidding  process.  What 
Seequa  is  implying  is  that  if  the  govern¬ 
ment  thinks  theircomputer  is  good,  you 
should  too.  This  28 -pound  portable  — 
small  enough  to  fit  under  an  airplane 
seat  —  costs  $1995,  and  comes  with 
two  5'/4-inch  160K  disk  drives,  128K 
RAM  (internally  expandable  to  256K, 
and  704K  externally),  and  8K  ROM 
(internally  expandable  to  40K).  Also 
included  are  a  9 -inch  green  phosphor 
screen  (80  by  25  characters),  standard 
color  capability  with  external  monitor, 
serial  and  parallel  ports,  and  fan.  The 
“standard  package”  contains  four 
pieces  of  16-bit  software:  MSDOS, 
MBASIC,  PerfectWriter,  and  Perfect- 
Calc.  They  don’t  supply  it,  but  CP/M- 
80  software  can  be  run.  Reader  Service 
No.  101. 


Yet  Another  Apple  Clone 

The  Icon  II,  from  Icon  Computer, 

costs  S849,  is  completely  compatible 
with  Apple  II  and  Franklin  Ace  1000, 
has  64K,  a  15 -key  numeric  pad,  and  a 
complete  90-day  warranty,  optionally 
increasable  to  one  year.  Reader  Service 
No.  103. 


Little  IBM  Talks  to  Bigger  IBM 

The  PC  Express  from  Intelligent 
Technologies  transforms  an  IBM  PC 
into  a  communications  workstation 
that  talks  to  other  PCs,  directly  acces¬ 
ses  several  mainframes,  handles  elec¬ 
tronic  mail,  and  performs  automated 
telephone  management.  The  package 
is  software  and  tutorials  on  diskette 
and  a  board  to  plug  into  the  PC  or  PC- 
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compatible  computer.  Several  com¬ 
munications  protocols  are  offered, 
including  synchronous  and  asynchro¬ 
nous.  The  PC  Express  I  communicates 
with  standard  asynchronous  main¬ 
frames  and  other  micros,  and  costs 
$895.  The  PC  Express  II  uses  SNA  to 
provide  327X  emulation  and  asynchro¬ 
nous  protocols  for  DEC  VT- 100/5  2 
terminal  emulation,  and  costs  $1295. 
Both  systems  have  automatic  answer, 
automatic  dialing  from  a  data  base  of 
phone  numbers,  detection  of  busy, 
ringing,  and  voice  answer,  a  full  text 
editor  to  create  those  deathless  mes¬ 
sages,  a  300  baud  chip,  and  an  RS-232 
connector  for  an  external  modem  with 
settings  up  to  19.2  kilobaud.  The  elec¬ 
tronic  mail  capabilities  permit  automa¬ 
tic  document  routing  through  Western 
Union,  The  Source,  CompuServe,  or 
any  personal  computer  with  auto¬ 
answer  and  asynchronous  communica¬ 
tions.  Data  can  be  sent  in  both  direc¬ 
tions  simultaneously.  A  PC  can  be  a 
host  to  another  local  or  remote  PC  or 
ASCII  terminal,  so  that  programs  can 
be  invoked,  run,  and  modified  locally 
or  remotely.  Reader  Service  No.  125. 


Incompatible  Formats 
Talk  to  Each  Other 

Disk  format  incompatibility  has 
long  been  a  problem  in  transferring 
files  from  one  computer  to  another. 
The  Transporter  from  Workman  and 
Associates  claims  to  be  the  solution 
to  the  problem.  Two  copies  are  not 
required  of  the  program;  only  the  re¬ 
ceiving  machine  must  run  CP/M;  and 
the  Transporter  can  send  itself  to  the 
other  machine  to  establish  two-way 
communications.  Supposedly  any  two 
CP/M  machines  can  be  talking  to  each 
other  in  20  minutes,  as  long  as  they 
have  compatible  communications 
ports  and  speeds;  or,  failing  that, 
modems  can  be  used.  The  included 
manual  explains,  they  say,  “the  process 
of  communication  between  CP/M  ma¬ 
chines.”  It  also  discusses  problems  of 
file  transfer,  from  baud  rates  to  port 
assignments.  A  modem  program  is  also 
on  the  disk,  as  are  other  file  transfer 
utilities.  $69.50  postpaid.  Reader 
Service  No.  107. 


Intelligent  Print  Buffer 

ANGEL  from  Ligo  Research  is 
an  intelligent  print  buffer,  with  64K 
RAM,  serial  and  parallel  input/output 
interfaces,  serial  baud  rate  from  110  to 
19.2K,  and  externally  switch-selectable 
parity  and  data  bit  size.  Serial  and 
parallel  can  be  switched  one  to  the 
other,  which,  they  claim,  eliminates  in¬ 
compatibility  between  computers  and 
printers.  “Page  mode”  permits  skipping 
pages,  reprinting  pages  that  might  have 
jammed  in  the  printer;  and  “page 
pause”  permits  single  sheet  printing. 
These  modes  are  software-  or  switch- 
selectable.  Space  compression  extends 
the  effective  buffer  size  to  128K. 
$295.  Reader  Service  No.  104. 


Trends:  Bargain  Computers 

I  just  bought  a  real  computer  for 
$40.  My  Timex-Sinclair  1000  Personal 
Computer,  which  had  been  retailing 
for  $69.95,  was  on  sale  for  $54.99  at 
Long’s.  Until  April  30,  Timex  was 
giving  a  $15  rebate,  so  my  Z80  com¬ 
puter  cost  $39.99  (plus  tax).  Yes,  I 
bought  it  at  a  drugstore.  No,  Long’s 
won’t  give  me  any  support,  but  Timex 
has  a  good  warranty.  There  are  several 
users’  groups.  A  magazine  and  a  num¬ 
ber  of  newsletters  are  devoted  to  the 
little  machine.  Not  much  memory,  you 
say?  Several  companies,  including 
Timex,  offer  a  16K  expansion  for 
under  $50.  Memotech  offers  a  64K 
RAM  for  $179.95.  You  don’t  like  the 
membrane  keyboard?  Memotech  also 
has  an  expansion  keyboard  that  plugs 
directly  into  the  back  of  the  Timex  for 
$99.95.  Timex  has  a  hundred-dollar 
printer.  No  wonder  this  is  the  best¬ 
selling  computer  in  the  world.  Every 
company  should  have  an  under-$50 
starter  computer.  When  the  beginners 
get  interested  in  computing,  then  sell 
them  the  more  expensive  peripherals, 
or  the  beefed-up  model.  Or  better  yet, 
make  the  inexpensive  model  upwardly 
compatible  with  the  more  powerful 
versions.  Atari?  Apple?  Radio  Shack? 
You  guys  listening?  Commodore  and 
TI  seem  to  be  getting  the  idea.  The 
VIC  20  and  the  99/44A  are  dropping 
to  the  hundred-dollar  range.  Reader 
Service  No.  111. 
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Smart  Optical  Mouse 

OptoMouse  2000  and  4000,  from 
USI,  are  optical  mice  whose  motions 
on  a  reflective  grid  are  translated  into 
input  to  a  computer’s  RS-232  port. 
The  2000  costs  $179  and  interfaces 
directly  with  the  IBM  PC  and  BASIC, 
and  has  a  WordStar  overlay  optionally 
available  for  $49.95.  Microprocessor- 
controlled,  with  two  buttons,  Opto¬ 
Mouse  interfaces  with  any  software 
that  has  cursor  positioning  capabilities. 
The  4000  has  four  buttons,  on-board 
8051  microprocessor  optical  system 
and  interface  circuitry,  eight  selectable 
baud  rates  from  1 10  to  9600,  and,  pre¬ 
sumably,  costs  more  (they  didn’t  list  a 
price).  Reader  Service  No.  113. 


6809  Single  Board  Micro 

The  6809  Control  Module  from 
Wintek  is  a  Motorola  6809 -based, 
single-board  computer  for  dedicated 
control,  protocol  conversion,  instru¬ 
mentation,  communications,  robotics, 
etc.  The  '4.5-by-6.5-inch  card  has  a  mi¬ 
croprocessor,  a  timer,  a  real-time  clock, 
two  RS-232  serial  ports,  four  parallel 
ports  with  handshaking,  and  can  ac¬ 
commodate  up  to  64K  of  RAM  and 
EPROM.  The  6809  Control  Module  is 
compatible  with  all  Wintek’s  I/O  mod¬ 
ules,  including  serial,  parallel,  IEEE- 
488,  driver/sensor,  floppy  disk  inter¬ 
face,  analog  interface,  parallel  bread¬ 
board,  console  I/O,  cassette,  and 
counter/timer  modules.  Wintek  also 
sells  developmental  software  for  the 
6809.  The  boards  cost  $245  each,  with 
up  to  a  50%  discount  for  quantity  pur¬ 
chases.  The  manual  costs  $5.  Reader 
Service  No.  115. 


Inexpensive  Graphics  Plotter 

The  Strobe  200,  from  Strobe 
Graphics  Systems,  holds  many  different 
kinds  of  widely  available  pens,  comes 
with  software  to  produce  line  and  bar 
graphs,  pie  charts,  and  print  alphanu- 
merics.  It  plots  applications  software, 
prints  overhead  slides,  and,  on  Apple 
only,  plots  VisiCalc  DIF  files  and 
dumps  the  screen  display  directly.  The 
200  costs  $795  for  IBM  PC,  Apple,  or 
CP/M  2.2.  An  on-board  RS-232C 
serial  interface  has  four  built-in  foreign 
language  character  sets,  proportional 
spacing,  and  costs  $  195.  Parallel  inter¬ 
face  cards  are  available  for  Apple  and 
Apple-compatible  computers  ($85), 
Osborne  ($90),  and  Commodore  and 
TRS-80  ($110).  The  Enhanced  Busi¬ 


ness  Graphics  Package,  a  spreadsheet 
graphics  program,  requiring  64K,  costs 
$195.  What  Strobe  calls  the  “industry 
standard”  Strobe  100  costs  $699. 

Reader  Service  No.  1 17. 


Is  “Comprehensive  Relational 
Data  Base  Management” 
a  Buzzword? 

DBPACK-II,  from  Compu-Draw, 

is  a  comprehensive  relational  data  base 
management  for  CP/ M  and  CDOS.  The 
number  of  files  (relations)  that  can  be 
opened  simultaneously  is  limited  only 
by  available  memory.  Each  relation 
can  have  up  to  65,535  records,  and 
each  record  up  to  65,535  fields.  Indi¬ 
vidual  relations  can  span  several  disks. 
Fields  can  be  any  of  several  data  types, 
including  text  string  data  of  up  to  254 
characters,  word-  or  line-oriented  text 
of  unlimited  length  (variable  record 
length  data  type),  floating  point, 
scientific  floating  point,  composite  nu¬ 
meric  data  with  up  to  three  subfields, 
date  data,  and  others.  Relations  are 
automatically  opened  as  needed.  Sev¬ 
eral  relations  on  a  disk  can  be  searched 
until  the  one  with  the  required  field  is 
found.  Modes  include  interactive  menu, 
interactive  command,  and  batch  com¬ 
mand,  with  no  limit  on  the  nesting  of 
command  files.  On-line  help  is  available 
at  all  times.  Sorts  or  any  other  relations 
can  be  performed  on  the  basis  of  an 
unlimited  number  of  keys.  Data  entry 
with  user-specified  error  checking  is 
easily  done.  There  is  password  protec¬ 
tion  at  the  relational  level.  Reports  are 
easily  generated  and  printed  in  many 
formats.  DBPACK-II’s  programming 
structures  include  DO,  WHILE,  and 
REPEAT  loops,  and  CASE  and  IF 
THEN  ELSE  constructs.  A  user- 
specified  log  of  all  activity  during  a 
session  can  be  sent  to  a  disk  file  or 
printer.  The  complete  package  costs 
$395.  Reader  Service  No.  119. 


PC  Becomes  Piano 

Turn  your  IBM  PC  into  a  playable 
musical  instrument  with  Visible  Piano 
from  Synthalytics.  You  get  a  plastic 
keyboard  overlay  that  makes  the  keys 
look  and  feel  “much  like  a  standard 
piano  keyboard.”  The  space  bar  acts 
like  the  sustain  pedal  on  a  piano.  With¬ 
out  additional  hardware,  this  software 
package  uses  the  monochrome  or  color 
graphics  display  and  built-in  speaker 
to  both  play  notes  and  display  them 
in  standard  pitch  notation.  Scores  can 
be  printed,  with  a  200-note  buffer  for 


page-length  printing.  In  edit  mode, 
you  can  change  a  score  with  full  cursor 
control.  Visible  Piano  has  an  eight - 
octave  range.  For  $45  you  get  disk, 
overlay,  instructions,  and  a  songbook. 
Reader  Service  No.  121. 


LISP  in  8,  16,  and  32  Bitth 

Cromemco  is  offering  LISP  on  its 
8-,  16-,  and  32-bit  Systems  One,  Two, 
and  Three,  with  virtual  storage,  string 
processing,  fixed-  and  floating-point 
arithmetic,  error  trapping,  interfacing 
with  non-LISP  procedures,  a  library  of 
over  150  utilities,  macro  facilities,  and 
a  table-driven,  user-modifiable  parser 
that  can  redefine  the  scanner  and 
define  new  LISP  syntax.  $595.  Reader 
Service  No.  123. 


Pearson  Correlations 
on  Your  Micro 

SL-MICRO,  from  Questionnaire 
Service  Company,  is  a  statistical  lan¬ 
guage  for  microcomputers.  This  statis¬ 
tical  package  processes  data  files  with 
up  to  32,600  cases  and  200  variables. 

A  free-to-fixed  field  conversion  utility 
makes  SL-MICRO  compatible  with 
data  base  packages.  It  has  variable  and 
value  labels,  long  variable  names,  mis¬ 
sing  values,  English  error  messages,  and 
offers  these  procedures:  Frequencies 
(with  statistics  and  histogram),  Cross¬ 
tabs  (including  chi-square),  Pearson 
Correlation  (with  an  optional  co- 
variance  table),  and  Multiple  Regres¬ 
sion  (with  Blockwise  and  Stepwise 
inclusion  levels).  You  need  CP/M  on 
Z80  with  two  disk  drives  and  48K,  or 
CP/M-86  with  128K  and  CBASIC. 
$250  including  manual,  or  manual 
alone  for  $15.  Reader  Service  No.  125. 


Hot  Rumor 

You  may  read  it  here  first,  particu¬ 
larly  if  you  don’t  get  Unique  (formerly 
the  UNIX  Software  List),  the  newslet¬ 
ter  for  UNIX  and  C  users  published  by 
InfoPro  Systems.  “FLASH  !  You  read 
it  here  first  (as  usual)!  ”  says  Unique. 
They  then  go  on  to  predict  that  this 
year  AT&T  will  be  offering  a  personal 
computer,  a  DBMS  for  UNIX,  and  a 
MAC-32 -based  desktop  UNIX  ma¬ 
chine.  Unique  is  $54  for  a  year  of 
monthly  issues  ($12  more  for  overseas 
airmail),  but  discounts  are  available  for 
nonprofit  organizations,  schools, bulk 
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and  multi-year  subscriptions,  and  indi¬ 
viduals  at  a  home  address.  Each  addi¬ 
tional  subscription  sent  in  the  same 
envelope  is  $10  per  year  extra  ($15 
overseas).  Reader  Service  No.  127. 


Most  of  What  You  Ever  Wanted 
to  Know  About  the  VIC  20 

Next  to  Timex,  the  VIC  20  is  per¬ 
haps  the  best-selling  computer  in  the 
world.  The  VIC  20  User  Guide,  by 
John  Heilborn  and  Ran  Talbott,  from 
Osborne/ McGraw-Hill,  is  addressed  to 
all  levels  of  expertise.  The  book  has 
operating  instructions  for  computer 
and  peripherals,  tutorials  in  Com¬ 
modore  BASIC  (including  instruction 
and  demonstration  programs  for  color 
graphics  and  sound),  and  detailed  pro¬ 
gramming  instruction  and  reference 
material.  System  architecture,  memory 
usage,  pinouts,  conversion  tables,  trig¬ 
onometric  functions,  and  sound  and 
display  characters  codes  are  all  said  to 
be  thoroughly  covered.  $14.95.  Reader 
Service  No.  129. 


Something  for  the  Kiddies? 

Above  Intelligence,  from  Eber- 
hard  Engineering,  P. C.,  is  “thought 
provoking  and  entertaining  software, 
targeted  for  the  sophisticated  execu¬ 
tive.”  It  includes  25  games  and  brain 
teasers,  “ideal,”  they  say,  “for  chil¬ 
dren,  or  people  without  computer  ex¬ 
perience.”  The  games  include  Hangman 
and  a  word  puzzle,  it  draws  a  Snoopy 
calendar,  and  “there  is  something  for 
everyone.”  But,  wait  a  minute,  they 
emphasize  that  the  “diskette  also 
includes  16  Nudes,  and  Nudes  with 
Calendars.”  Hmmm.  Above  Intelli¬ 
gence  runs  on  TRS-80  Models  II,  12, 
and  16  with  Daisy  Wheel  II  or  line 
printer,  and  costs  $49.95.  Reader 
Service  No.  13 1 . 


Calling  Forth 

For  any  interested  Forth  folks, 
we  recently  learned  of  two  upcoming 
fall  conferences. 

For  beginning  or  professional 
Forth  enthusiasts,  the  5th  Annual 
Forth  Convention  will  be  held  this 
October  14-15  at  the  Hyatt  Palo  Alto 
in  Palo  Alto,  California.  Focusing 
on  the  future  of  Forth-based  systems, 
topics  will  include  Forth-based  instru¬ 
ments,  operating  systems,  and  machines 


at  the  hardware  level.  Anyone  inter¬ 
ested  in  submitting  abstracts  should 
keep  them  to  less  than  100  words, 
and  get  them  in  by  August  1st.  To  get 
an  author’s  kit,  write  to:  The  Forth 
Interest  Group,  Convention  Program 
Chairman,  P.O.  Box  1105,  San  Carlos, 
CA  94070  (or  call  the  FIG  hot  line  at 
415-962-8653). 

This  November  23-25,  the  5th 
Annual  Forth  Modification  Laboratory 
(FORML)  Conference  will  be  held  at 
the  Asilomar  Conference  Center  in 
Pacific  Grove,  California.  Not  intended 
for  beginners,  the  conference  will 
focus  on  guiding  the  evolution  of 
Forth.  Suggested  topics  include:  Hard¬ 
ware  Forth  Implementation,  Large 
Address  Space  Environments,  Multi¬ 
programming  Architectures,  Nucleus 
Variations,  Operating  System  Environ¬ 
ments,  System  Generation  Techniques, 
Program  Development  Methodologies, 
and  Applications.  Anyone  interested 
in  submitting  an  abstract  should  also 
keep  it  to  no  longer  than  100  words, 
and  have  it  in  by  September  6th.  To 
obtain  registration  information  and  an 
author’s  kit,  write  to.  FORML,  P.O. 
Box  51351,  Palo  Alto,  CA  94303. 
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Letters 

(Continued  from  page  10) 


I  have  “Easter  egg”  hunted  for  that  infor¬ 
mation  for  several  months  now.  After 
reading  Gene’s  article,  the  Digital  Research 
instruction  began  to  make  sense.  I  still 
don’t  understand  how  they  assign  the 
DPB  to  the  various  drives.  My  CP/M  is 
Lifeboat,  written  for  North  Star.  I  know 
North  Star’s  method  of  turning  “on”  the 
bits  for  the  different  drives,  but  I  can’t 
seem  to  find  the  “proper  byte”  to  do 
that  bit.  Anyway,  I  would  like  to  be  able 
to  have  my  disk  drives  access  different 
DPB’s.  I  have  a  BASF  DSDD,  Tandon 
DSDD  and  two  Shugart  SSDD,  so  you  see 
my  dilemma  when  the  Tandon  tracks 
faster  than  the  BASF,  and  the  Shugart  is 
pulling  up  the  rear  like  the  tortoise. 

I  sincerely  enjoy  your  magazine,  hav¬ 
ing  been  an  intermittent  subscriber  since 
DDJ  No.  28.  Thank  you  for  assistance 
and  the  rest  and  enjoyment  that  the,  DDJ 
brings  me. 

Very  truly  yours, 

J.  E.  McMurray 
P.O.  Box  6772 
Columbia,  SC  29260 

Solutions  to  SRA 

Dear  Sirs: 

In  the  article  “Shifts  and  Rotations 
on  the  Z80,”  on  the  SRA  (Shift  Right 
Arithmetic)  instruction,  the  author  says: 
“There  may  be  some  practical  reason  for 
leaving  bit  1  on,  but  I  am  not  aware  of  it.” 

The  reason  for  this  is  simple.  SRA  is 
an  arithmetic  shift  and  therefore  retains 
the  sign  of  a  2’s  complement  signed  num¬ 
ber.  SRA’s  valid  input  range  is  -128  to 
+127  while  SRL  (which  is  unsigned)  goes 
from  0  to  255.  SRA  is  used  on  the  MS 
byte  and  is  then  followed  by  RR  instruc¬ 
tions  for  the  rest  of  the  bytes  for  multi¬ 
byte  precision  signed  numbers. 

R.  Tim  Coslet 

2001  Manhattan,  No.  3 17 

Palo  Alto,  CA  94303 


More  Small -C  Fixes 

Dear  Doctor  Dobb, 

Users  of  the  Small-C  Compiler  ver¬ 
sion  2  (DDJ  Nos.  74  and  75)  may  be 
interested  in  the  following  modifications, 
which  improve  the  code  generated  by  the 
compiler: 

(1)  One  of  the  “optimizations”  in  the 
function  peephole  ()  actually  replaces 
good  code  with  worse,  trading  the  code 
sequence 
POP  D 
MOV  A,L 
STAX  D 

for  a  subroutine  call.  Both  sequences  are 
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three  bytes  long,  but  the  original  code 
executes  faster.  Lines  288-290  and  351- 
353  in  peepholeQ  should  be  deleted. 

(2)  The  function  loadargc()  puts  the 
number  of  arguments  in  a  function  call 
into  register  A,  using  the  code  MVI  A,n. 
In  the  special  case  when  there  are  no  ar¬ 
guments,  A  can  be  cleared  by  the  single¬ 
byte  instruction  XRA  A.  To  have  the 
compiler  do  this,  change  lines  48-50  of 
loadargc()  to 

if  (val) 

-[  ot(“MVI  A,”);  outdec(val);  nl();> 
else 

ol(“XRA  A”); 

(3)  The  following  changes  improve  the 
code  generated  for  an  indirect  function 
call.  Changes  are  needed  in  three  places 
First,  add  the  following  to  the  runtime 
library: 

CCDCAL:  ENTRY 
PCHL 

and  make  the  concomitant  changes  to 
listings  four  and  five  of  the  compiler.  Sec¬ 
ond,  change  the  code  generator  function 
callstk()  to 
callstk  (  ) 

-[  call  (“CCDCAL”); 

Third,  change  lines  209-217  of  callfunc- 
tion()  to 

while  (streq(  lptr,  “)”  ==  0) 
i  if  (endst())  break; 
if  (ptr)  /*  direct  call  */ 

-{  expression(&const,  &val); 
push(); 

Y 

else  /*  calling  HL  */ 
i  push(); 

expression(&const,  &val); 

swapstk();  /*  get  call  address 
back  in  HL  */ 

y 

nargs  =  nargs  +  BPW ; 
if  (match(“,”)==  0)  break 

Y 

These  changes  save  three  bytes  of  code 
and  12  clock  cycles  (8080  timing)  for 
each  indirect  function  call,  using  the  old 
8080  programming  trick  of  faking  a  dy¬ 
namic  call  (i.e.,  a  call  to  the  address  in 
HL)  by  a  call  to  a  subroutine  which  is 
just  the  instruction  PCHL. 

Sincerely, 

Paul  F.  West 

401  Nob  Hill  PL,  No.  5 

Ann  Arbor,  MI  48103 
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LETTERS 


Mending,  but  Commending 

To  the  Editor: 

An  error  appeared  in  two  of  the  fig¬ 
ures  illustrating  “B-Tree  ISAM  Concepts” 
in  your  June  issue.  In  Figure  3,  the  root 
node  should  show  “L”  in  place  of  “I.” 
Similarly,  both  root  nodes  in  Figure  4 
should  show  “R”  instead  of  “K.”  Un¬ 
less  I’ve  missed  something,  the  network 
shown  in  Figure  3  could  never  find  key 
“K”  because  the  comparison  at  the  root 
node  would  send  it  down  the  wrong 
path. 

Otherwise  the  article  was  excellent, 
as  was  your  June  issue  as  a  whole.  The 
article  raised  a  question  in  my  mind. 
There’s  a  design  trade-off  between  a 
many-layered  tall  tree  and  a  flatter  tree 
with  more  elements  at  each  node,  and 
therefore  more  reliance  on  sequential 
processing  within  each  level.  What  are  the 
considerations  that  would  affect  the 
choice  of  “height”  versus  “thickness”  in 
a  particular  application? 

Please  continue  to  feature  the  IBM 


Personal  Computer  in  your  articles.  I 
intend  to  use  both  programs  that  you  ran 
this  month  in  my  study  of  assembly  lan¬ 
guage.  I  also  find  the  articles  on  comput¬ 
er  science  and  applications  in  higher-level 
languages  very  helpful.  I  even  skim  through 
the  articles  on  CP/M  to  pick  up  some  use¬ 
ful  concepts.  Please  keep  up  the  good 
work. 

Sincerely, 

Michael  G.  McCarter 

Reliance  Ins.  Co. 

4  Penn  Center  Plaza 

Philadelphia,  PA  19103 

A  “ Fix”  for  the 
IBM  Graphics  Printer 

Dear  Editor, 

Thanks  for  publishing  “Printing 
Graphics  on  the  IBM  PC,”  in  your  June 
1983  issue.  As  I  mentioned  in  the  article, 
the  differences  in  control  ROMs  for  the 
Epson  printer  can  cause  trouble.  I  now 
believe  that  users  attempting  to  imple¬ 
ment  the  program  I  submitted,  on  the 


IBM  Graphics  Printer,  will  have  some  mi¬ 
nor  problems.  Basically,  the  control  ROM 
for  the  IBM  Graphics  Printer  is  different 
from  that  available  from  Epson  under 
their  GRAFTRAX  option. 

The  “fix”  for  users  equipped  with 
the  IBM  Graphics  Printer  is  simple.  The 
20th  line  of  the  listing  reads  as  follows: 
LSPC  DB  27, ‘A’, 8, 13, 10,‘  $  ’ 

;Sets  printer  to  8/72” 

Changing  the  line  to: 

LSPC  DB  27, ‘A’, 8,27, ‘2’,  13,10/$’ 
;Sets  printer  .... 

should  correct  the  problem.  I  still  have 
not  been  able  to  locate  a  configuration 
equipped  with  the  Graphics  Printer,  so  I 
haven’t  verifited  the  fix.  The  data  I  do 
have  indicate  that  if  there  is  a  problem, 
this  should  correct  it.  Basically,  the  Epson 
with  GRAFTRAX  accepts  the  Escape  ‘A’ 
sequence  and  acts  on  it  immediately.  The 
IBM  version  sets  line  spacing  on  the  Es¬ 
cape  ‘A’  sequence,  but  does  not  imple¬ 
ment  the  new  spacing  until  it  receives  an 


EDITORIAL 


Once  again,  we’ve  published  our  largest  issue  ever!  Our 
expansion  is  exciting;  but  at  the  same  time,  we  are  con¬ 
scious  that  bigger  is  not  always  better.  In  this  case,  however, 
our  increase  in  size  will  allow  us  options  we  haven’t  had  in 
the  past.  With  more  editorial  pages,  we  have  the  opportu¬ 
nity  to  present  more  variety  each  month,  even  when  we  run 
larger  pieces,  as  we  have  in  this  issue  and  in  the  last. 

Among  the  things  we’ve  wanted  to  devote  more  space 
to  are  reviews  of  books,  software,  and  occasionally  hard¬ 
ware.  We  have  recently  been  updating  our  lists  of  reviewers, 
and  feel  that  this  is  an  appropriate  time  to  extend  an 
invitation  to  potential  reviewers.  If  you  are  interested  in 
doing  reviews  for  Dr.  Dobb 's  —  whether  on  books,  soft¬ 
ware,  or  hardware  —  drop  us  a  note  outlining  your  quali¬ 
fications  and  interests.  We’ll  get  right  back  with  you  con¬ 
cerning  particulars. 

*  *  * 

If  you  have  ever  wanted  to  have  an  impact  on  the 
quality  of  articles  in  our  magazine,  this  could  be  your  big 
chance.  Since  Dr.  Dobb’s  is,  among  other  things,  a  reader 
forum,  our  readership  has  traditionally  filled  gaps  and 
corrected  any  occasional  oversights.  Even  so,  this  feedback 
mechanism  can  be  slow  and  cumbersome,  and  getting  com¬ 
ments  into  the  Letters  column  can  take  a  while.  Recent 
mail  pointing  out  some  of  our  blind  spots  set  us  to  thinking. 
As  the  microcomputer  industry  has  become  increasingly 
complex  and  diverse,  it  has  become  difficult  for  any  of  us 
to  stay  on  top  of  every  area.  Our  current  technical  advisors 


have  done  an  excellent  job;  but  as  the  variety,  specifi¬ 
city,  and  volume  of  material  for  the  magazine  has  increased, 
so  has  the  need  for  greater  breadth  in  our  resources.  Conse¬ 
quently,  we  think  it  appropriate  to  include  among  our 
advisors  a  board  of  referees.  The  function  of  the  board  will 
be  to  provide  insights  on  specific  technical  topics,  and  to 
make  suggestions  regarding  material  for  DDJ.  Since  much 
of  our  best  input  comes  from  our  readers,  we  can  think  of 
no  better  place  to  turn  for  qualified  people. 

We’re  looking  for  experts  in  various  subject  areas  to 
review  perhaps  two  to  four  manuscripts  per  month.  The 
subject  categories  include,  but  are  not  limited  to:  mathe¬ 
matics,  graphics,  programming  languages  (of  all  sorts), 
utilities,  and  operating  systems  (including  MS-DOS,  CP/M- 
86,  CP/M-68K,  UNIX  and  UNIX  look-alikes).  This  addi¬ 
tion  to  our  technical  crew  should  ensure  more  accurate 
and  complete  information,  and  provide  a  better  level  from 
which  to  begin  the  usual  reader  dialogue. 

In  gratitude  for  their  generous  service,  referees  will 
receive  a  complimentary  subscription  to  DDJ ,  and  will  have 
their  names  and  professional  affiliations  listed  in  the  maga¬ 
zine.  Those  who  are  interested  in  participating  should 
contact  us  with  information  about  their  areas  of  specialty 
and  interest.  We’d  love  to  talk  with  you. 


Reynold  Wiggins 
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Escape  ‘2’  sequence.  On  the  GRAFTRAX, 
incidentally,  this  latter  sequence  resets 
the  printer  to  “power  up”  spacing. 

I  hope  this  has  not  caused  too  many 
of  your  readers  a  problem. 

I  haven’t  been  doing  much,  but  I’ll 
be  back  in  touch  one  of  these  days.  I’m 
waiting  for  the  Cl  C  compiler  right  now, 
so  maybe  I’ll  be  able  to  submit  someC  in 
the  future.  That  might  reduce  the  listing 
volume  to  something  less  than  encyclo¬ 
pedic  dimensions. 

Dan  W.  Daetwyler 
Route  5,  Box  5 18 A 
Springdale,  AR  72764 

C  Clearly  With 
Descriptive  Operators 

Dear  Editor: 

The  C  systems  programming  language 
is  powerful  and  concise  —  sometimes  too 
concise.  Indistinct  operator  names  cause 
confusion  and  error.  These  three  pairs  of 
operator  names  cause  the  greatest  trouble: 


=  (assignment) 

VS. 

=  =  (equality  test) 

&  (bitwise  and) 

vs. 

&&  (logical  and) 

1  (bitwise  or) 

vs. 

1  1  (logical  or) 

The  subtle  differences  in  the  meanings 
of  the  bitwise  and  logical  operators  aggra¬ 
vate  the  problem.  Fortunately,  a  remedy 
exists. 

Making  operator  names  more  distinct 
reduces  confusion.  The  C  preprocessor  of¬ 
fers  a  simple  way  to  do  this.  For  example: 

#  define  and  && 

/*  logical  and  now  written  ‘and’  */ 

#  define  or  I  I 

/*  logical  or  now  written  ‘or’  */ 

#  define  equals  =  = 

/*  equality  test  now  written  ‘equals’*/ 
integer  x ; 
if  (x  equals  10) 

/*  This  replaces  “if  (x  ==  10)”  and 
reduces  errors  like  the  use  of 
“if  (x  =  10).”  */ 

Using  distinct  operator  names  makes 
programs  easier  to  read,  write,  and  debug, 
making  better  use  of  the  C  language. 
Sincerely, 

Bryan  M.  Willman 
309  Iowa  Avenue,  No.  3 
Iowa  City,  IA  52240 

A  Reader’s  Rebuttal 

Good  morning, 

I  am  writing  you  as  a  concerned  sci¬ 
entist  and  subscriber.  I  am  surprised  that 
H.  T.  Gordon’s  article  did  not  undergo  as 
much  scrutiny  as  many  of  your  program 
listings  do.  As  a  mathematician  and  com¬ 
puter  scientist  I  find  his  last  paragraph 
disturbing,  so  let  me  explain  and  state  a 
rebuttal. 


•  Every  number  theory  book  contains  a 
chapter  on  divisibility,  and  therein  are 
most,  if  not  all,  the  “algorithms”  de¬ 
scribed  by  Gordon. 

•  “Algorithms”  are  also  found  in  many 
reference  texts  in  computer  science, 
such  as  Knuth’s,  The  Art  of  Computer 
Programming,  Volume  1,  Addison- 
Wesley. 

•  These  divisibility  “algorithms”  devel¬ 
oped  by  the  author  are  basically  related 
to  the  mod  function  (X  is  divisible  by 
9  if  and  only  if  x  mod  10  is).  This  easily 
explains  generalizations  to  other  bases. 

•  Discovery  of  these  algorithms  dates 
back  to  the  Chinese  some  5000  years 
ago. 

•  Archimedes  and  Newton  would  have 
been  offended  at  Gordon’s  statement 
about  “computational  drudgery,  in 
the  pre- computer  era.” 

•  There  are  algorithms  for  divisibility  by 
any  prime  number. 

•  Gordon,  in  using  the  term  “random¬ 
ness,”  is  referring  to  uniformly 
distributed  random  numbers.  His  1/3 
test  does  not  work  on  the  set  -[  1,2,3, 
.  .  . ,  N  ]■  for  N  large. 

I  tried  not  to  be  caustic,  but  may 
have  failed.  Mathematics  is  an  old  science, 
and  as  such  it  has  many  followers.  Please 
watch  thy  written  words  .... 

Sincerely, 

Dr.  Georges  Grinstein 
Professor,  Computer  Sciences 
Fitchburg  State  College 
Fitchburg,  MA  01420 


IBM’s  Fortran  Compiler  — 

Where  to  Put  the  Blame 

Dr.  Dobb: 

In  the  Letters  section  of  the  May  issue 
Messrs.  Glass  and  Landis  presented  some 
benchmark  comparisons  which  include 
execution  time  of  IBM’s  Fortran  compiler 
written  by  Microsoft  and  implemented 
on  the  PC. 

Lamenting  the  agonizingly  slow  exe¬ 
cution  time  of  Microsoft’s  Fortran,  they 
lay  the  blame  on  Microsoft’s  Pascal, 
since  the  Fortran  compiler  is  written  in 
Pascal. 

However,  the  execution  of  the  target 
language  (Intel  8086  machine  language) 
should  not  be  affected  by  whether  the 
compiler  is  written  in  Pascal,  BASIC, 
or  whatever.  After  all,  the  compiler  sim¬ 
ply  translates  ASCII  source  code  into  the 
appropriate  binary  code. 

Also,  Microsoft  Pascal  is  written  in 
Microsoft  Pascal,  and  it  does  very  well  in 
benchmark  tests  such  as  the  algorithm  in 
Jim  Gilbreath’s  article,  “A  High-Level 
Language  Benchmark,”  in  the  September 
1981  issue  of  Byte  magazine. 

Perhaps  the  poor  performance  re¬ 
ported  was  in  part  caused  by  not  turning 
off  the  default  DEBUG  faility,  which  can 
add  considerably  to  execution  time.  If 
not,  the  blame  is  on  the  Fortran  compiler 
—  not  the  language  it  is  written  in. 
Sincerely, 

Daniel  L.  Lee 
SourceWare 

1401  E.  55th  St.,  Suite  601 
Chicago,  IL  60615 
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Specialist  Symbols 

Back  in  March  we  published  a  note 
from  J.  Dempsey,  asking  for  solutions 
to  the  problem  of  editing,  printing,  and 
processing  the  kind  of  non-ASCII  sym¬ 
bols  that  turn  up  in  such  professional 
specialties  as  Linguistics.  Several  readers 
responded,  usually  with  suggestions  to  try 
one  or  another  software  product  or  with 
accounts  of  how  they  looked  for  solutions 
to  the  same  problem  with  little  more  suc¬ 
cess  than  Dempsey  had  had.  We  passed 
copies  of  all  those  letters  on  to  Dempsey; 
perhaps  we  will  hear  more  from  him  later. 

There  seems  to  be  general  agreement 
that  it  isn’t  difficult  to  display  specialist 
symbols  on  the  screens  of  machines  that 
support  soft  character  sets  (Atari,  IBM 
PC,  etc.).  It  may  be  quite  difficult  to  get 
one’s  word  processing  software  to  handle 
them.  There  is  no  easy  solution  to  the 
problem  of  keyboard  entry,  at  least  with 
existing  products.  The  IBM  PC’s  trick  of 
entering  three  decimal  digits  through  the 
numeric  keypad  with  the  Alt  key  held 
down  is  the  most  flexible  one  we  know  of 
from  an  OEM,  but  the  best  solution  is  for 
the  software  to  provide  the  ability  to  map 
any  key  to  any  symbol.  The  PE  editor  for 
the  PC  has  that  feature  (see  last  month 
under  “Cheap  Thrills”),  but  it’s  best 
when  the  ability  is  provided  as  part  of,  or 
as  an  extension  of,  the  operating  system. 

There  does  seem  to  be  a  satisfactory 
way  of  printing  specialist  symbols.  For 
evidence,  see  the  letter  from  Prof.  Dr. 
Neuhaus  of  Munster,  reproduced  on  page 
12.  His  letter  is  the  best  endorsement  of 
the  Fancy  Font  product  that  we’ve  seen; 
in  the  original,  it  is  clear  that  every  char¬ 
acter  was  produced  by  it,  including  the 
elegant  letterhead. 

We  don’t  know  how  one  represents  a 
specialist  symbol  as  input  to  Fancy  Font. 
If  it  is  by  way  of  a  single,  non-ASCII 
byte  .  .  .  and  if  one  could  make  one’s 
screen  hardware  use  the  same  byte  value 
to  display  the  same  user-defined  symbol 
.  .  .  and  if  one’s  word  processor  could 
handle  those  byte  values  .  .  .  and  if  one 
had  an  acceptable  way  of  entering  them 
from  the  keyboard  .  .  .  then  one  would 
have  a  pretty  good  start  at  handling  the 
problem. 

CP/M  3  Earns  Its  Plus 

In  June  we  went  on  at  some  length 
about  how  the  sector-buffering  scheme 
of  CP/M  Plus  didn’t  seem  to  have  much 
effect  on  the  kind  of  sequential  I/O  done 
by  the  bulk  of  CP/M  commands.  This 


month  we  can  report  a  much  happier  con¬ 
clusion.  We  have  made  some  tests  of  direct- 
access  disk  I/O  under  CP/M  Plus,  and  it  is 
very  quick  indeed. 

Comparative  benchmarks  are  not 
simple  things  to  organize.  It  takes  some 
thought  to  ensure  that  the  comparative 
results  are  indeed  comparable.  We  spent 
some  time  devising  a  set  of  BASIC  pro¬ 
grams  that  would  exercise  direct -access 
I/O  in  a  realistic  way,  and  yet  which 
would  be  simple  enough  for  other  people 
to  duplicate  on  almost  any  hardware. 
Take  the  time  now  to  read  through  the 
programs. 

The  Test  Programs 

The  first  is  MAKEDIR  (Listing  1, 
page  18).  It  creates  a  direct-access  file; 
the  variables  NUMBYTES  and  NUMREC 
determine  its  size.  For  a  realistic  test,  the 
file  must  be  large  enough  to  span  several 
extents  (use  several  directory  entries)  and 
many  tracks.  Line  1040  must  be  adjusted 
to  reflect  the  size  of  a  physical  disk  sector, 
and  line  1060  to  reflect  the  size  of  an 
extent,  in  the  test  system.  The  same  lines 
1010  through  1070  appear  in  all  the  other 
programs  and  must  be  identical  in  all. 

MAKEDIR  writes  a  file  sequentially, 
but  it  does  it  with  direct-access  I/O  ser¬ 
vices.  Its  execution  time  will  be  dominated 
by  I/O  and  should  be  about  the  same  as 
if  the  file  were  being  written  with  sequen¬ 
tial  operations. 

In  order  to  get  comparable  results, 
the  test  file  should  be  written  only  once, 
and  then  used  in  place  in  all  subsequent 
tests  in  both  systems.  If  the  file  is  erased 
and  rewritten,  the  distance  between  data 
and  directory  and  the  span  of  tracks 
across  the  data  may  change,  and  that 
would  make  the  results  incompatible. 

The  second  program  is  RANDINPT 
(Listing  2,  page  21).  It  is  a  naive  test  of 
direct  access:  it  simply  generates  200  ran¬ 
dom  integers  in  the  range  of  1  to  NUMREC 
and  reads  the  corresponding  records.  Its 
accesses  will  exhibit  no  clustering  (or  to 
put  it  another  way,  its  “working  set”  is 
the  whole  file).  Applications  that  process 
records  in  batches  (and  so  are  dominated 
by  I/O  time)  will  usually  have  some  kind 
of  ordering  or  clustering  to  their  accesses. 
Interactive  programs  may  retrieve  ran¬ 
domly  scattered  records  as  RANDINPT 
does,  but  will  not  do  so  in  a  tight  loop. 
The  execution  time  of  an  interactive  pro¬ 
gram  will  be  dominated  by  keying  delays. 
However,  if  we  measure  not  the  total 


running  time  of  RANDINPT  but  its  run¬ 
ning  time  divided  by  the  number  of  rec¬ 
ords  it  retrieves,  we  will  have  an  idea  of 
the  speed  at  which  one  record  can  be  re¬ 
trieved.  The  time  to  retrieve  one  record 
may  be  an  important  factor  in  the  re¬ 
sponse  time  of  an  interactive  program. 

Take  special  note  of  line  1005  in 
RANDINPT.  It  is  essential  to  set  the 
pseudo-random  generator  to  a  known 
value  before  every  run.  Otherwise  we 
can’t  be  positive  that  the  results  under 
the  two  systems  are  truly  comparable. 

When  sectors  are  larger  than  records, 
I/O  time  is  not  determined  by  the  num¬ 
ber  of  logical  records  that  are  read.  Two 
things  are  important:  first,  the  number  of 
disk  sectors  that  must  be  transferred,  and 
second,  the  number  of  times  the  system 
must  go  to  the  directory.  RANDINPT 
counts  these  things  in  two  different  ways. 
Whenever  the  current  record  falls  in  a  dif¬ 
ferent  sector  from  the  prior  one,  it  counts 
a  “sector  transition.”  In  a  system  with  a 
single  sector  buffer,  every  sector  transi¬ 
tion  requires  another  sector  to  be  read. 
Whenever  the  current  record  falls  in  a 
different  extent  than  the  prior  one, 
RANDINPT  counts  an  “extent  transition.” 
In  a  system  without  directory  buffering, 
an  extent  transition  forces  a  read  of  the 
directory.  The  program  also  keeps  track 
of  the  number  of  unique  sectors  and  ex¬ 
tents  that  are  accessed,  in  order  to  give  an 
idea  of  how  well  the  file  was  covered. 

The  third  program  is  RANDUPDT 
(Listing  3,  page  21).  It  visits  the  same 
sequence  of  records  as  does  RANDINPT, 
but  it  also  updates  each  record,  forcing 
the  system  to  write  as  well  as  read.  Its 
mean  time  to  update  one  record  is  again 
an  indication  of  the  response  time  of  an 
interactive  system. 

The  RAND  programs  are  not  repre¬ 
sentative  of  any  real  applications  (except 
interactive  ones,  as  noted).  With  the  fourth 
program,  SKIPUPDT  (Listing  4,  page  22), 
we  attempt  to  model  the  class  of  applica¬ 
tions  that  do  batched  updates  of  a  direct- 
access  database.  Imagine  an  order-entry 
application  in  which  incoming  orders  are 
entered  interactively  during  the  day. 
The  line  items  of  the  orders  are  batched 
in  a  sequential  file.  Each  evening,  these 
transactions  are  sorted  by  part  number, 
and  then  applied  in  sequence  to  update 
an  inventory  database.  The  resulting 
sequence  of  accesses  is  ordered  in  that  it 
updates  records  in  ascending  order  by  key, 
but  random  in  that  not  all  records  are 
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Mr.  D.  E.  Cortesi 

Dr.  Dobb’s  Journal 

Box  E 

1263  El  Camino  Real 
Menlo  Park,  CA  94025 

U.  S.  A.  April  6,  1983 


Re:  Dr.  Dobb’s  Clinic;  Number  77,  March  1963  "Demsey's  Dilemma" 


Dear  Mr.  Cortesi, 

Linguists  have  for  some  time  been  used  to  laser  printers  on  main¬ 
frame  computers  that  allow  individual  character  definition  and  the  use  of  special 
alphabets.  Donald  Knuth’s  METAFONT  alphabet  design  system  is  one  of  the  more 
powerful  software  tools  available  for  that  purpose. 

On  microcomputers  there  is  a  very  professionly  done  package  by  SoftCraft, 
8726  S.  Sepulaveda  Boulevard,  Suite  1641,  Los  Angeles.  The  Fancy  Font  system 
was  introduced  in  1982.  It  has  been  used  extensively  in  my  department.  We  created 
various  fonts.  One  of  them  is  an  implementation  of  the  International  Phonetic 
Alphabet.  Line  3  of  Mr.  Dempsey’s  text  example  looks  like  this: 

[dokkun  darfjun  tji:  bu  i:n  Jl:ri:nforu:J“  cube  vc] 

There  are  special  symbols  for  diphthongs:  ai  au  oy  ,  nasals:  ce  e  i  etc. 

A  major  problem  with  special  alphabets  is  their  QWERTY  keyboard  repre¬ 
sentation  and  their  logical  ASCII  value  ordering.  These  are  normally  quite  different. 
If  Mr.  Dempsey  is  interested  he  may  contact  me  for  further  information. 


Sincerely  yours, 
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Figure  1. 
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updated.  It  is  this  kind  of  skip-sequential 
processing  that  SKIPUPDT  attempts  to 
model.  It  generates  approximately  200 
keys,  each  key  being  incremented  by  at 
least  1  but  no  more  than  10  from  the 
prior  key. 

Skip -sequential  processing  causes 
many  fewer  sector  and  extent  transitions 
than  does  random  processing.  According¬ 
ly  we  can  expect  that  SKIPUPDT  will 
have  a  much  shorter  running  time  than 
RANDUPDT,  at  least  under  CP/M  2.2 
where  the  transitions  have  the  greatest 
impact.  Its  total  time  should  be  indicative 
of  the  relative  speeds  of  a  real  skip- 
sequential  program  in  the  two  systems. 

The  last  program,  TREEUPDT  (List¬ 
ing  5,  page  24),  is  an  attempt  to  model 
the  access  patterns  of  a  B+Tree  database 
manager  (see  the  tutorial  by  Deppe  and 
Bartholomew  in  the  June  issue  of  DDJ). 
A  tree-structured  file  has  an  heirarchical 
index.  The  topmost  level  is  a  single  record 
of  keys,  which  points  to  several  records 
of  keys,  which  point  to  many  records  of 
keys,  which  in  turn  point  to  lots  and  lots 
of  data  records. 

The  TREEUPDT  program  simulates  a 
number  of  random  updates  of  records 
stored  in  such  a  tree.  It  assumes  that  the 
topmost  index  record  would  be  kept  in 
storage,  and  that  the  next  two  levels  are 
stored  in  adjacent  records  at  the  front  of 
the  file.  It  reads  one  of  the  first  eight  rec¬ 
ords  to  simulate  retrieval  of  an  index  node; 
reads  one  of  the  next  64  records  to  simu¬ 
late  index  retrieval  at  the  next  level;  and 
finally  updates  one  of  the  remaining  rec¬ 
ords  to  simulate  access  to  a  data  record. 
The  per-transaction  time  of  TREEUPDT 
should  tell  something  about  the  perfor¬ 
mance  of  a  tree-structured  database. 


The  Results 

These  programs  were  run  under  CP/M 
2.2  and  CP/M  Plus  in  the  same  system. 
The  system  is  a  moderately  fast  one  as 
8-bit  systems  go.  Its  CPU  is  a  Z80  run¬ 
ning  at  4MHz;  it  has  single-sided,  double¬ 
density,  8-inch  disk  drives  (Shugart  801s, 
6  millisecond  step  rate).  The  BIOS  for 
CP/M  2.2  uses  separate  sector  buffers  for 
reading  and  writing.  The  BIOS  for  CP/M 
Plus  supplies  70Kb  of  sector  buffers,  as 
described  in  this  column  in  June.  The  ex¬ 
act  timings  given  below  would  be  repeat- 
able  only  in  another  system  with  exactly 
the  same  hardware  and  software.  How¬ 
ever,  the  ratio  between  the  times  for  the 
two  systems  should  be  constant  in  any 
one  system,  with  the  single  exception 
that  the  CP/M  Plus  times  are  dependent 
on  the  number  of  sector  buffers  available. 

Under  CP/M  2.2  the  programs  were 
loaded  and  run  one  after  another  under 
the  MBASIC  5.0  interpreter.  Under  CP/M 
Plus  the  programs  were  run  as  separate 
commands,  with  a  return  to  the  operating 


system  between  each.  That  was  necessary 
because  CP/M  Plus  discards  its  buffered 
sectors  each  time  the  CCP  takes  control. 
If  we  hadn’t  exited  from  the  MBASIC 
environment  between  each  program,  sec¬ 
tors  brought  in  by  one  program  would 
have  still  been  available  when  the  next 
one  started. 

Times  were  taken  with  a  stopwatch 
and  recorded  to  the  nearest  second.  The 
results  appear  in  Table  1  (page  16). 
Each  row  of  the  table  represents  a  run. 
The  column  “No.  of  records”  is  the 
count  of  data  records  read  or  updated  in 
the  run.  The  “Total”  columns  show  run 
time  in  seconds;  the  “Per  rec.”  columns 
show  run  time  divided  by  data  records 
processed.  The  last  column  shows  the 
ratio  of  CP/M  Plus  run  time  divided  by 
CP/M  2.2  run  time,  as  a  percentage. 

The  first  surprise  appears  in  the  first 
line:  MAKEDIR  ran  slower  under  CP/M 
Plus.  The  difference  in  times  is  not  very 
significant,  but  it  is  puzzling.  CP/M  Plus 
is  usually  about  10  percent  faster  at 
sequential  I/O. 

The  lines  headed  RANDINPT  (1024) 
and  RANDUPDT  (1024)  show  that  CP/M 
Plus  can  be  strikingly  faster  at  pure  ran¬ 
dom  access.  It  read  a  random  record  in 
about  one-fourth,  and  updated  one  in 
about  one- fifth,  the  time  taken  by  CP/M 
2.2.  One  noticeable  difference  between 
the  systems  was  that,  under  CP/ M  Plus,  it 
took  as  long  as  13  seconds  to  close  a  file. 
RANDUPDT  caused  many  modified  sec¬ 
tors  to  accumulate  in  storage.  When  the 
CLOSE  statement  was  executed,  the  sys¬ 
tem  spent  many  seconds  dumping  them 
all  to  disk.  You  would  be  well  advised  to 
issue  frequent  closes  to  “checkpoint” 
your  random  files  under  CP/M  Plus. 


The  RANDUPDT  test  revealed  a  dis¬ 
advantage  of  our  two- buffered  BIOS  for 
2.2;  a  BIOS  with  a  single  sector  buffer 
might  actually  run  faster  on  this  test.  The 
cause  lies  in  this  typical  sequence  of 
operations: 

read  data  sector  A 
write  to  data  sector  A 
read  the  directory 
read  data  sector  B 
write  to  data  sector  B 
The  usual  2.2  BIOS  would  have  to  dump 
the  updated  sector  A  to  disk  before  read¬ 
ing  the  directory.  Ours  didn’t;  it  held 
sector  A  in  the  write  buffer  and  read  the 
directory  sector(s)  and  sector  B  into  its 
read  buffer.  Not  until  the  call  to  write 
sector  B  did  it  need  to  purge  its  write 
buffer.  Alas,  by  then  it  had  moved  the 
disk  arm  to  the  track  of  sector  B,  and  had 
to  do  an  additional  seek  before  it  could 
write  sector  A. 

Under  CP/M  2.2,  the  disk  drive 
sounded  a  rhythmic  “doo- wacka-doo” 
as  it  moved  between  the  directory  and 
the  data  area.  Extent  transitions  were 
obviously  dominating  the  run  time  of  the 
RAND  tests.  In  order  to  find  out  how 
much  effect  these  had,  we  modified  line 
1030  of  the  two  RAND  programs  to  show 
only  128  records  in  the  file.  As  a  result, 
the  programs  confined  their  activity  to 
the  first  extent  of  the  file,  eliminating 
extent  transitions.  The  result  of  these  runs 
is  shown  in  Table  1  in  the  lines  headed 
RANDINPT  (128)  and  RANDUPDT  (128). 
Compare  them  to  the  lines  just  above 
them. 

It  appears  that  extent  transitions 
(i.e.,  directory  accesses)  account  for 
about  three-fourths  of  the  per-record 
time  under  CP/M  2.2,  but  for  less  than 


Table  I 

Summary  of  the  results  of  direct-access  I/O  tests 
run  on  CP/M  2.2  and  CP/M  Plus. 


No.  of 

CP/M  2.2 

CP/M  3.0 

CPM3/CPM2 

Program 

Records 

Total 

Per  rec. 

Total 

Per  rec. 

(as  pet) 

MAKEDIR 

1024 

48 

0.05 

53 

0.05 

110% 

RANDINPT  (1024) 

200 

164 

0.82 

43 

0.21 

26% 

RANDINPT  (128) 

200 

45 

0.23 

23 1 

0.12 

51% 

RANDUPDT  (1024) 

200 

333 

1.67 

652 

0.33 

20% 

RANDUPDT  (128) 

200 

73 

0.37 

32 1 

0.16 

44% 

SKIPUPDT 

192 

66 

0.34 

m 

CD 

0.33 

97% 

TREEUPDT 

100 

261 

2.61 

363 

0.36 

14% 

Note  1 :  this  run  was  dominated  by  CPU  time;  the  disk  was  idle  during  much  of  the  run. 
Note  2:  includes  file-close  time  of  about  13  seconds. 

Note  3:  includes  file-close  time  of  about  6  seconds. 
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half  of  it  under  CP/M  Plus.  This  demon¬ 
strates  the  effectiveness  of  the  directory 
hashing  tables  and  directory  buffers  used 
by  CP/M  Plus.  Note  that  the  CP/M  Plus 
time  for  these  runs  was  not  dominated 
by  I/O  time;  after  the  first  16  records  or 
so,  all  data  were  in  storage  and  the  disk 
simply  stopped  moving. 

The  performance  of  the  two  systems 
was  nearly  identical  on  the  SKIPUPDT 
test.  Sector  buffering  has  little  effect 
when  the  program  never  returns  to  the 
same  sector!  A  skip-sequential  applica¬ 
tion,  like  a  purely  sequential  one,  will  not 
run  significantly  faster  under  CP/M  Plus. 
The  tiny  improvement  that  does  show  is 
probably  due  to  directory  hashing. 

However,  it  seems  that  access  to  a 
tree-structured  database  will  be  greatly 
improved.  The  relative  speed  of  CP/M 
Plus  in  the  TREEUPDT  test  is  really 
impressive;  it  ran  seven  times  faster  than 
CP/M  2.2!  Indeed,  under  CP/M  Plus  the 
per-transaction  time  of  TREEUPDT  was 
almost  identical  to  that  of  RANDUPDT. 
TREEUPDT  makes  two  more  disk  accesses 
per  transaction,  but  since  these  are  accesses 
to  the  frequently  used  “index”  sectors, 
they  were  almost  always  storage-to-storage 
moves  rather  than  I/O  operations.  A  data¬ 
base  system  that  uses  a  B+Tree  organiza¬ 
tion  should  show  markedly  better  perfor¬ 
mance  under  CP/M  Plus  (would  some 
reader  care  to  verify  that  with  a  real 
program?). 

Summary' 

In  the  area  of  disk  I/O  performance, 
then,  it  appears  that  CP/M  Plus  is  not 
significantly  slower  than  CP/M  2.2  for 
sequential  and  skip -sequential  I/O,  while 
its  direct  access  operations,  given  a  suf¬ 
ficient  buffer  area,  are  very  much  faster. 

In  June  we  said  that  a  single  48  Kb 


Dr.  Dobb’s  Clinic  (Text  begins  on  page  10) 

Listing  One 


1000  '  MAKEFILE. BAS:  create  large  direct-access  file 
1010  DEFINT  A-Z 

1020  NUMBYTES  =128  bytes  per  record 

1030  NUMREC  =  1024  records  in  file  ( 128*1024=128KB) 

1040  RECSEC  =  1024\NUMBYTES  IK  sectors  in  use 

1050  NUMSEC  =  NUMREC \RECSEC  disk  sectors  in  file 

1060  RECEXT  =  1 6384\NUMBYTES : '  16KB  extents  in  use 

1070  NUMEXT  =  NUMRECNRECEXT  directory  extents  in  file 

2000  PRINT  "Opening  file";CHR$(7)  start  the  watch 

2010  OPEN  "R",#1, "TEST. DIR", NUMBYTES 

2020  FIELD  #1,  2  AS  KEY$,  2  AS  DAT$,  NUMBYTES-4  AS  FILL$ 
3000  FOR  KEY  =  1  TO  NUMREC 
3010  LSET  KEY$  =  MKI$(KEY) 

3020  LSET  DAT$  =  MKI$(0) 

3030  LSET  FILL$  =  STRING$( 124 , "  ") 

3040  PUT  #1 , KEY 

3050  PRINT  KEY 

3060  NEXT  KEY 

4000  PRINT  :  PRINT  "Closing  file" 

4010  CLOSE  #1 

4020  PRINT  CHR$(7) ;"File  closed"  stop  the  watch 


9000  END 


End  Listing  One 


system  bank  would  be  sufficient  extra 
hardware  for  CP/M  Plus.  That  remains 
our  recommendation  for  systems  where 
direct  access  I/O  is  not  a  significant  part 
of  daily  operations.  When  direct  access  is 
used  a  lot,  or  for  important  applications, 
we  recommend  that  a  CP/M  Plus  system 
be  given  one  additional  48Kb  bank  for 


sector  buffers  (two,  if  the  working  set  of 
the  application  is  large).  The  improved 
performance  should  justify  the  cost. 

A  response  on  behalf  of  Digital  Research 
to  the  June  Clinic  arrived  too  late  to  in¬ 
clude  in  this  issue.  It  will  be  presented 
in  the  Letters  column  next  month.  -Ed. 

(Listings  1-5  on  pages  18-26) 


Dr.  Dobb’s  Clinic  (Listing  continued,  text  begins  on  page  10) 

Listing  Two 

1000  '  RANDINPT.BAS:  retrieve  many  records,  strictly  at  random 
1005  RANDOMIZE( 4093)  ensure  repeatability 

1010  DEFINT  A-Z 

1020  NUMBYTES  =128  bytes  per  record 

1030  NUMREC  =  1024  records  in  file  ( 128*1024=128KB) 

1040  RECSEC  =  1024NNUMBYTES  IK  sectors  in  use 

1050  NUMSEC  =  NUMRECNRECSEC  disk  sectors  in  file 

1060  RECEXT  =  1 6384NNUMBYTES : '  16KB  extents  in  use 

1070  NUMEXT  =  NUMRECNRECEXT  directory  extents  in  file 

1075  NEWSEC  =  0  :  OLDSEC  =  .0  :  SECTRANS  =  0 


18 

418 


Dr.  Dobb’s  Journal,  Number  82,  August  1983 


1080  NEWEXT  =  0  :  OLDEXT  =  0  :  EXTTRANS  =  0 
1085  DIM  SECTOR ( NUMSEC ) ,  EXTENT( NUMEXT) 

2000  PRINT  "Opening  file";CHR$(7)  start  the  watch 
2010  OPEN  "R",#1, "TEST. DIR", NUMBYTES 

2020  FIELD  #1,  2  AS  KEY$,  2  AS  DAT$,  NUMBYTES-4  AS  FILL$ 
3000  FOR  COUNT  =  1  TO  200 

3010  KEY  =  INT ( RND*NUMREC )  :  KEY  =  KEY-(KEY=0) 

3020  NEWSEC  =  1  +  KEY\RECSEC 

3030  SECTOR (NEWSEC)  =  1 

3040  SECTRANS  =  SECTRANS-(OLDSECONEWSEC) 

3050  OLDSEC  =  NEWSEC 

3060  NEWEXT  =  1  +  KEYVRECEXT 

3070  EXTENT (NEWEXT)  =  1 

3080  EXTTRANS  =  EXTTRANS- (OLDEXTONEWEXT) 

3090  OLDEXT  =  NEWEXT 

3100  GET  # 1 , KEY 

3110  PRINT  COUNT,  KEY,  NEWSEC,  NEWEXT 

3120  NEXT  COUNT 

4000  PRINT  :  PRINT  "Closing  file" 

4010  CLOSE  #1 

4020  PRINT  CHR$(7) ;"File  closed"  stop  the  watch 

5000  COUNT  =  0 

5010  FOR  J  =  1  TO  NUMSEC 

5020  COUNT  =  COUNT  +  SECTOR (J) 

5030  NEXT  J 

5040  PRINT  COUNT;"  unique  sectors  visited  of"; NUMSEC 

5050  COUNT  =  0 

5060  FOR  J  =  1  TO  NUMEXT 

5070  COUNT  =  COUNT  +  EXTENT(J) 

5080  NEXT  J 

5090  PRINT  COUNT;"  unique  extents  visited  of"; NUMEXT 
5100  PRINT  SECTRANS;"  sector  transitions" 

5110  PRINT  EXTTRANS;"  extent  transitions" 

9000  END 

Listing  Three 


End  Listing  Two 


1000  '  RANDUPDT.BAS:  update  many  records,  strictly  at  random 
1005  RANDOMIZE( 4093)  ensure  repeatability 

1010  DEFINT  A-Z 

1020  NUMBYTES  =128  bytes  per  record 

1030  NUMREC  =  1024  records  in  file  ( 128*1024=128KB) 

1040  RECSEC  =  1024NNUMBYTES  IK  sectors  in  use 

1050  NUMSEC  =  NUMREC \RECSEC  disk  sectors  in  file 

1060  RECEXT  =  16384\NUMBYTES:  '  16KB  extents  in  use 

1070  NUMEXT  =  NUMREC \RECEXT  directory  extents  in  file 

1075  NEWSEC  =  0  :  OLDSEC  =  0  :  SECTRANS  =  0 

1080  NEWEXT  =  0  :  OLDEXT  =  0  :  EXTTRANS  =  0 

1085  DIM  SECTOR ( NUMSEC ) ,  EXTENT( NUMEXT) 

2000  PRINT  "Opening  file";CHR$(7)  start  the  watch 
2010  OPEN  "R",#1, "TEST. DIR", NUMBYTES 

2020  FIELD  #1,  2  AS  KEY$,  2  AS  DAT$ ,  NUMBYTES -4  AS  FILL$ 

3000  FOR  COUNT  =  1  TO  200 

3010  KEY  =  INT (RND* NUMREC)  :  KEY  =  KEY-(KEY=0) 

3020  NEWSEC  =  1  +  KEYXRECSEC 

3030  SECTOR ( NEWSEC )  =  1 

3040  SECTRANS  =  SECTRANS- (OLDSECONEWSEC) 

3050  OLDSEC  =  NEWSEC  (Continued  on  next  page) 
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Dr.  Dobb’s  Clinic  (Listing  continued,  text  begins  on  page  10) 

Listing  Three  (Continued) 

3060  NEWEXT  =  1  +  KEYNRECEXT 

3070  EXTENT (NEWEXT)  =  1 

3080  EXTTRANS  =  EXTTRANS-(OLDEXTONEWEXT) 

3090  OLDEXT  =  NEWEXT 

3100  GET  # 1 , KEY 

3101  LSET  DAT$=MKI$( 1+CVI(DAT$) ) 

3102  PUT  # 1 , KEY 

3110  PRINT  COUNT,  KEY,  NEWSEC,  NEWEXT,  CVI(DAT$) 

3120  NEXT  COUNT 

4000  PRINT  :  PRINT  "Closing  file" 

4010  CLOSE  #1 

4020  PRINT  CHR$(7) ;"File  closed"  stop  the  watch 

5000  COUNT  =  0 

5010  FOR  J  =  1  TO  NUMSEC 

5020  COUNT  =  COUNT  +  SECTOR(J) 

5030  NEXT  J 

5040  PRINT  COUNT;"  unique  sectors  visited  of"; NUMSEC 

5050  COUNT  =  0 

5060  FOR  J  =  1  TO  NUMEXT 

5070  COUNT  =  COUNT  +  EXTENT(J) 

5080  NEXT  J 

5090  PRINT  COUNT;"  unique  extents  visited  of"; NUMEXT 
5100  PRINT  SECTRANS;"  sector  transitions" 

5110  PRINT  EXTTRANS;"  extent  transitions" 

9000  END 

End  Listing  Three 

Listing  Four 

1000  '  SKIPUPDT.BAS:  update  records  in  skip-sequential  order 
1005  RANDOMIZE( 4093)  s'  ensure  repeatability 
1010  DEFINT  A-Z 

1020  NUMBYTES  =  128  bytes  per  record 

1030  NUMREC  =  1024  records  in  file  ( 128*1024=128KB) 

1040  RECSEC  =  1 024\NUMBYTES  IK  sectors  in  use 

1050  NUMSEC  =  NUMRECNRECSEC  disk  sectors  in  file 

1060  RECEXT  =  1 6384NNUMBYTES :  '  16KB  extents  in  use 

1070  NUMEXT  =  NUMREC \RECEXT  directory  extents  in  file 

1075  NEWSEC  =  0  :  0LDSEC  =  0  :  SECTRANS  =  0 

1080  NEWEXT  =  0  :  OLDEXT  =  0  :  EXTTRANS  =  0 

1085  DIM  SECTOR (NUMSEC),  EXTENT ( NUMEXT) 

2000  PRINT  "Opening  file";CHR$(7)  start  the  watch 
2010  OPEN  '"R",#1, "TEST. DIR", NUMBYTES 

2020  FIELD  #1,  2  AS  KEY$,  2  AS  DAT$,  NUMBYTES-4  AS  FILL$ 

3000  KEY  =  0  :  COUNT  =  0 

3003  WHILE  KEY  <  NUMREC- 10 

3010  KEY  =  KEY  +  INT(RND«9)  +  1 

3015  COUNT  =  COUNT  +  1 

3020  NEWSEC  =  1  +  KEYNRECSEC 

3030  SECTOR (NEWSEC)  =  1 

3040  SECTRANS  =  SECTRANS- (OLDSECONEWSEC) 

3050  OLDSEC  =  NEWSEC 

3060  NEWEXT  =  1  +  KEY\RECEXT 
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3070  EXTENT (NEWEXT)  =  1 

3080  EXTTRANS  =  EXTTRANS-(OLDEXTONEWEXT) 

3090  OLDEXT  =  NEWEXT 

3100  GET  # 1 , KEY 

3101  LSET  DAT$=MKI$( 1+CVI(DAT$) ) 

3102  PUT  # 1 , KEY 

3110  PRINT  COUNT,  KEY,  NEWSEC,  NEWEXT,  CVI(DAT$) 

3120  WEND 

4000  PRINT  :  PRINT  "Closing  file" 

4010  CLOSE  #1 

4020  PRINT  CHR$(7) ;"File  closed"  stop  the  watch 

5000  PRINT  COUNT;"  records  processed  of";NUMREC 

5005  COUNT  =  0 

5010  FOR  J  =  1  TO  NUMSEC 

5020  COUNT  =  COUNT  +  SECTOR(J) 

5030  NEXT  J 

5040  PRINT  COUNT;"  unique  sectors  visited  of";NUMSEC 

5050  COUNT  =  0 

5060  FOR  J  =  1  TO  NUMEXT 

5070  COUNT  =  COUNT  +  EXTENT(J) 

5080  NEXT  J 

5090  PRINT  COUNT;"  unique  extents  visited  of"; NUMEXT 
5100  PRINT  SECTRANS;"  sector  transitions" 

5110  PRINT  EXTTRANS;"  extent  transitions" 

9000  END 


Listing  Five 


End  Listing  Four 


1000  '  TREEUPDT.BAS:  approximate  a  B+TREE  update  pattern 
1005  RANDOMIZE( 4093)  ensure  repeatability 

1010  DEFINT  A-Z 

1020  NUMBYTES  =128  bytes  per  record 

1030  NUMREC  =  1024  records  in  file  ( 128*1024=128KB) 

1040  RECSEC  =  1024XNUMBYTES  IK  sectors  in  use 

1050  NUMSEC  =  NUMREC \RECSEC  s'  disk  sectors  in  file 

1060  RECEXT  =  1 6384XNUMBYTES :  '  16KB  extents  in  use 

1070  NUMEXT  =  NUMREC \RECEXT  directory  extents  in  file 

2000  PRINT  "Opening  file" ; CHR$( 7)  start  the  watch 

2010  OPEN  "R",#1, "TEST. DIR", NUMBYTES 

2020  FIELD  #1,  2  AS  KEY$,  2  AS  DAT$,  NUMBYTES- 4  AS  FILL$ 
3000  FOR  COUNT  =  1  TO  100 
3010  K 1  =  INT(RND*8)+1 

3020  GET  #1,K1  top-level  index  read 

3030  K2  =  INT(RND*64)+9 

3040  GET  #1,K2  2nd-level  index  read 

3050  K3  =  INT( RND* ( NUMREC-73 ) )+73 

3060  GET  #1,K3  : '  data  record 

3070  LSET  DAT$  =  MKI$(CVI(DAT$) ) 

3080  PUT  #1 ,K3 

3090  PRINT  COUNT,  K1,  K2,  K3 

3100  NEXT  COUNT 

4000  PRINT  :  PRINT  "Closing  file" 

4010  CLOSE  #1 

4020  PRINT  CHR$( 7) ; "File  closed"  stop  the  watch 
9000  END 

End  Listing  Five 
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Serial  to  Parallel 

A  Flexible  Utility  Box 


What  do  you  do  when  you  have 
the  chance  to  buy  a  working 
IBM  Selectric  I/O  typewriter  for 
a  bargain  price?  Buy  it,  right?  Especially 
when  everything  is  all  ready  to  plug  in 
and  run.  During  the  happy  trip  home, 
you  recall  that  the  demo  computer  used  a 
parallel  port  to  drive  the  Selectric. 

A  parallel  port  on  the  demo  comput¬ 
er?  Minor  oversight,  vou  have  a  couple 
of  spare  serial  ports  and  there  shouldn’t 
be  a  bit  of  trouble  hooking  up  something 
to  work  right  away.  Guess  again! 

Sound  like  a  familiar  story?  We’ve 
all  been  there  somewhere  along  the  way. 


The  Problem 

I  needed  a  serial-to -parallel  converter 
—  just  a  simple  device  to  take  the  serial 
data  from  the  RS-232C  serial  port  on  my 
Heath  H-8  and  convert  it  to  parallel  with 
strobe  and  handshaking.  Because  I  wanted 
to  have  the  flexibility  of  also  using  my 
H-89  with  the  Selectric,  that  excluded 
the  option  of  actually  building  a  parallel 
port  into  the  computer  itself.  Whatever  I 
decided  to  use,  however,  should  not  re¬ 
quire  special  initialization  or  an  extra 
driver  program  to  make  it  run  properly;  it 
should  be  treated  no  differently  than  my 
serial-input  Okidata  82A. 


A  Chain  of  Boxes 

Figure  1  (page  31)  gives  an  overview 
of  the  computer  system.  The  computer’s 
UART  sends  serial  data  to  the  serial-to- 
parallel  box  yet  to  be  built.  The  parallel 
data  from  the  box  goes  directly  into  the 
Selectric  interface  unit.  The  data,  even  at 
this  point,  are  still  plain  ASCII;  the  code 
conversion  to  either  Selectric  Correspon¬ 
dence  or  BCD  code  takes  place  in  the 
interface  unit  and  needs  no  special  atten¬ 
tion.  In  the  return  direction,  note  that  a 
busy  signal  comes  from  the  interface  unit 
when  a  character  is  received.  The  signal 
is  passed  on  through  to  the  computer’s 
UART.  Thus,  the  printing  operation  in¬ 
volves  sending  a  single  character,  waiting 
for  the  Selectric  to  print  it,  sending 
another  character,  waiting,  and  so  on. 


by  Alan  D.  Wilcox 
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In  Search  of  the  Wheel 

Rather  than  reinvent  the  wheel,  I 
first  checked  the  design  Heath  used1  for 
their  parallel  interface  board:  two  back- 
to-back  8251  USART’s  (Universal  Syn¬ 
chronous/Asynchronous  Receiver/ Trans¬ 
mitters)  !  Not  only  was  that  more  hard¬ 
ware  than  reasonable,  but  it  also  required 
a  special  driver  program  for  initialization 
before  it  would  even  run  at  all.  There  had 
to  be  a  better  way. 

A  search  of  the  literature  turned  up 
some  useful  ideas.  Steve  Ciarcia2  published 
the  schematic  of  a  serial-to-parallel  con¬ 
verter  using  the  AY3-1015  UART  (Univer¬ 
sal  Asynchronous  Receiver/ Transmitter) 
and  NE-555  timer;  while  simple  and 
quick  to  build,  it  did  not  have  the  flexi¬ 
bility  of  being  able  to  easily  change  the 
baud  rate.  Two  more  of  his  designs3’ 4 
solved  this  data-speed  flexibility  problem 
by  using  a  switch-settable  baud-rate 
clock;  these  serial- parallel  circuits  were 
only  a  small  part  of  much  larger  designs. 
In  general,  though,  I  liked  his  approach 
to  data  conversion. 

Isenson5  had  a  completely  different 
solution  to  his  parallel  interface  problem. 
Rather  than  deal  with  the  serial  data  at  all, 
he  simply  connected  into  his  computer 
bus  for  the  parallel  data  and  used  the 
computer’s  internal  UART  only  for  device 
decoding.  As  far  as  the  computer  was 
concerned,  it  was  writing  data  to  a  serial 
port.  He  used  the  CPU’s  WAIT*  (wait  not) 
line  to  hold  the  CPU  in  a  wait  state  until 
his  printer  was  ready  to  accept  more  data. 
This  approach  would  work  in  my  applica¬ 
tion,  but  would  hardly  allow  for  the  flexi¬ 
bility  of  hooking  the  Selectric  to  either 
the  H-8  or  the  H-89. 

Isenson  did  circumvent  one  critical 
design  issue  with  my  Selectric:  handshak¬ 
ing.  Pulling  the  WAIT*  low  when  the 
printer  is  busy  causes  an  immediate  halt 
in  CPU  activity  —  not  a  bit  more  data  gets 
sent  to  the  printer  until  the  WAIT*  is 
released.  On  the  other  hand,  in  an  appli¬ 
cation  not  using  WAIT*  the  computer’s 
UART  will  finish  sending  the  current  char¬ 
acter  even  though  it  receives  a  busy  signal 
from  the  printer.  Ordinarily  this  really  is 
not  too  critical  —  most  parallel  printers 
on  the  market  have  buffering,  so  that 
some  data  can  still  be  received  even  after 
a  busy  signal  has  been  sent  to  the  CPU’s 
UART.  Not  so  my  Selectric.  There  is  no 
buffer  at  all  in  the  solenoid-driver/code¬ 
conversion  circuit.  This  means  that  the 
sending  UART  in  the  computer  has  to  re¬ 
ceive  a  busy  signal  immediately  after 


sending  a  character  or  else  it  will  start 
sending  a  second  character  before  the 
Selectric  can  accept  it.  Unfortunately,  the 
second  character  has  already  started  by 
the  time  the  Selectric  sends  back  its  busy 
signal.  Somehow,  a  pseudo-busy  has  to 
be  sent  to  the  CPU  before  its  UART  starts 
a  second  character. 

What  was  thought  to  be  a  simple  dis¬ 
traction  is  now  getting  to  the  level  of  a 
major  project! 

Circuit  Design 

The  design  of  the  completed  serial- 
parallel  converter  is  shown  in  Figure  2 
(pages  32-33).  The  heart  of  the  unit  is  the 
baud-rate  clock  and  the  UART;  the  rest 
is  circuitry  I  found  necessary  to  make  the 
unit  work  with  the  Selectric.  While  de¬ 
signing  it,  I  made  the  unit  as  general  as 
possible  so  that  it  could  be  used  with  any 
computer  with  a  serial  port.  In  addition,  I 
had  in  mind  that  my  serial- parallel  con¬ 
verter  might  also  be  used  to  get  parallel 
data  not  only  to  a  printer,  but  also  to  a 
PROM  programmer  sometime  in  the 
future. 

The  flow  of  serial  data  from  the  com¬ 
puter  is  from  the  DB-25  connector  (pin 
3),  through  the  MC-1489  line  receiver, 
and  into  the  UART.  When  the  UART  has 
received  a  complete  character,  the  DAV 
(Data  Available)  line  at  pin  19  goes  high 
to  signal  that  the  parallel  output  is  valid; 
the  parallel  output  will  remain  valid  until 
another  character  is  received.  In  this  de¬ 
sign,  the  DAV  signal  is  used  for  two  pur¬ 
poses:  the  first  is  to  trigger  the  74123 
one-shot  so  a  strobe  pulse  goes  out  to  the 
printer,  and  the  second  is  to  reset  the 
UART  DAV  line  by  sending  a  low  signal  to 
the  RDAV*  (Reset  Data  Available  not) 
input  on  pin  18.  The  normal  sequence  of 
operation,  then,  is  that  data  come  in 
serially  until  a  complete  character  is  re¬ 
ceived.  This  makes  DAV  true  and  triggers 
the  strobe  to  the  printer.  At  the  same 
time  as  the  strobe,  RDAV*  is  activated  to 
prepare  the  UART  for  a  new  character. 

A  word  on  the  strobe  might  be  in 
order  at  this  point.  The  momentary  high 
signal  on  DAV  is  very  brief,  somewhat  less 
than  a  microsecond.  My  Selectric,  and 
most  other  printers,  need  a  microsecond 
or  longer  pulse  duration  for  proper  opera¬ 
tion.  The  74123  one-shot,  as  designed, 
provides  a  pulse  on  the  order  of  2  /isec. 
This  has  not  proved  to  be  critical,  but  it 
can  be  adjusted  if  desired  by  changing  the 
resistor  and  capacitor  (R6,C2)  on  pins  14 
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and  15  of  IC7.  The  strobe  itself  is  low-true. 

One  unexpected  hitch  arose  in  the 
development  of  the  circuit:  the  Selectric 
has  automatic  line  feed  (LF).  This  meant 
that  all  I  needed  to  send  to  the  Selectric 
was  a  carriage  return  (CR)  and  it  would 
go  to  the  next  line  by  itself.  I  could  make 
allowance  for  this  by  changing  the  operat¬ 
ing  system  to  send  just  the  CR  character 
and  not  send  the  LF.  However,  the  Oki- 
data  was  set  to  receive  the  CR/LF  pair 
and  that’s  the  way  the  Selectric  better 
take  it.  (At  this  point,  it  was  “Take  it 
...  or  else.”)  My  solution  is  the  logic 
using  the  7404  and  7430  IC’s.  When  a  line 
feed  character  (0 AH )  appears  on  the  data 
bus  from  the  UART,  the  logic  combines  to 
bring  pin  8  of  the  7430  low.  If  the  switch 
is  positioned  to  “delete  LF,”  then  pin  1 
of  the  7400  is  pulled  low,  preventing  the 
initiation  of  the  strobe  pulse.  Without  a 
strobe  pulse,  the  data  bus  values  are  ig¬ 
nored  by  the  printer  and  the  undesired 
line  feed  gets  no  further. 

The  selection  of  the  Western  Digital 
BR1941  baud -rate  clock  was  made  pri¬ 
marily  because  of  its  availability  and 
many  switch-settable  baud  rates.  There 
are  actually  several  frequency  options: 
the  BR1941-00  and  the  BR1941-06  which 
both  take  the  5.0688  MHz  crystal,  and 
the  BR1941-05  which  takes  a  4.9152  MHz 
crystal.  The  one  sold  by  mail  is  the  com¬ 
mon  BR 1941-00.  The  IC  can  provide  two 
different  frequencies,  one  for  a  receiver 
and  another  for  a  transmitter.  In  the 
present  design,  however,  the  receiver 
clock  is  the  only  one  used.  Its  output  on 
pin  3  is  at  16  times  the  baud  rate  selected 
by  the  switches.  For  example,  if  1200- 
baud  serial  data  are  to  be  received,  then 
the  frequency  of  the  signal  at  pin  3  is  16 
x  1200  or  19.2  KHz.  This  clock  signal 
goes  directly  into  the  UART  RCP  (Re¬ 
ceiver  Clock)  on  pin  17. 

A  decision  needs  to  be  made  as  to 
what  data  format  is  expected  to  be  con¬ 
verted  from  serial  to  parallel.  In  my  case, 
I  expected  to  be  receiving  the  same  serial 


data  as  the  Okidata,  and  that  happened  to 
be  in  the  format  of  1  stop  bit,  8  bits  per 
character,  and  no  parity.  All  this  needs  to 
be  set  only  one  time  and  never  needs 
changing  unless  the  system  is  being  al¬ 
tered.  No  special  initialization  data  are 
required  to  be  sent  from  the  computer  to 
make  it  run.  This  one-time  setup  is  ac¬ 
complished  by  the  five  switches  connected 
to  the  UART  pins  35-39  and  will  be  dis¬ 
cussed  later. 

The  handshaking  between  tne  com¬ 
puter  and  the  Selectric  turned  out  to  be 
easier  than  I  first  imagined.  True,  I  did 
need  to  provide  the  pseudo-busy  signal, 
as  I  call  it,  back  to  the  CPU’s  UART 
before  the  Selectric  even  sent  its  busy 
signal,  but  it  was  simply  done.  Here’s  how 
it  works:  the  instant  the  start  bit  for  the 
first  character  comes  in  (on  pin  3  of  the 
DB-25  connector),  the  MC-1489  line  re¬ 
ceiver  sends  it  to  one  section  of  the  74123 
one-shot.  The  output  of  the  one-shot 
(pin  12),  which  had  been  high  until  now, 
suddenly  drops  low  and  causes  the  output 
of  the  MC-1488  line  driver  to  go  high.  In 
my  system,  a  high  signal  (+12  volts)  going 
out  on  the  RTS  (Request  To  Send,  pin  4) 
is  taken  to  mean  that  the  printer  is  busy 
and  cannot  accept  more  data.  Therefore, 
the  high  output  of  the  MC-1488  causes 
the  CPU’s  UART  to  see  a  busy  on  the 
handshaking  line.  This  pseudo- busy  ap¬ 
pears  during  the  first  character  quickly 
enough  to  prevent  the  CPU’s  UART  from 
sending  the  next  character;  the  busy  stays 
on  for  about  28  msec.  Meanwhile,  as  soon 
as  the  first  character  has  ended,  the  busy 
line  from  the  Selectric  goes  high.  After 
being  inverted  in  the  7400  to  a  low  level, 
it  prevents  the  MC-1488  line  driver  from 
changing  its  output  (which  is  still  high)  to 
a  low  (-12  volts)  not-busy.  Once  the 
Selectric  busy  has  arrived,  the  one-shot 
can  time-out  and  is  no  longer  needed.  At 
a  typing  rate  of  12  characters  per  second, 
the  total  time  is  about  83  msec,  for  each 
character,  so  the  arbitrary  time  for  the 
one-shot  can  be  quite  flexible. 


Construction 

The  whole  prototype  serial-to-parallel 
converter  fits  easily  on  one  4V£-by-6-inch 
prototype  board.  A  list  of  parts  for  the 
board  is  shown  in  Table  I  (page  34); 
The  actual  parts  layout  was  not  critical, 
and  I  positioned  parts  for  simple  inter¬ 
connections.  A  wire-wrap  approach  could 
have  been  taken,  but  I  preferred  to  just 
solder  wires  point-to-point  —  soldering 
the  wires  is  a  bit  neater  and  easier  to 
change.  The  board  itself  was  mounted 
inside  a  walnut  desk -top  enclosure. 

The  cable  going  to  the  Selectric  had 
a  standard  card-edge  connector  intended 
for  a  TRS-80  parallel  port.  I  chose  to 
provide  a  mate  for  it  rather  than  change 
the  connector  itself.  For  the  prototype, 
this  involved  etching  a  small  piece  of 
double-sided  circuit  board  to  match  the 
pins.  Recently,  I  noticed  that  the  local 
Radio  Shack  store  now  has  a  prototype 
board  with  a  suitable  card -edge  connec¬ 
tor  already  etched  on  it.  The  serial  data 
DB-25  connector  was  mounted  to  the 
circuit  board  with  small  angle  brackets. 
The  only  other  connections  to  the  board 
are  for  power,  and  I  used  the  card-edge 
connections  on  the  other  end  of  the 
board  for  mem. 

The  BR-1941  requires  two  supply 
voltages  for  operation.  Be  sure  not  to 
apply  one  without  the  other.  I  accidentally 
turned  off  one  supply,  and  the  result  was 
disaster  for  the  baud -rate  clock.  The 
UART  may  require  two  supplies  also, 
depending  on  which  UART  you  use.  The 
AY3-1014  I  used  needs  only  +5;  others 
may  need  -12  on  pin  2. 

Rather  than  build  a  power  supply,  I 
chose  one  from  the  many  on  the  market. 
The  Micromint  supply  with  +5  and  ±  12 
was  ideal  for  the  job.  The  transformer 
is  at  the  AC  plug  (like  many  calculator 
chargers),  and  the  voltage  regulation  is  on 
a  small  circuit  board  which  1  put  in  the 
same  box  as  the  converter  itself. 
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Initial  Setup  and  Test 

When  first  setting  up  the  converter 
unit,  make  sure  that  the  system  is  really 
what  you  think  it  is.  Is  RTS-high  taken  to 
mean  a  busy?  Is  the  serial  data  at  1200 
baud?  Check  by  running  CONFIGUR  (or 
whatever  program  your  particular  operat¬ 
ing  system  uses  to  set  up  serial  ports).  Be 
sure  your  cables  are  going  to  the  right 
pins  of  the  connectors.  I  can  plug  into 
two  sockets  on  the  back  of  the  H-89: 
either  the  340Q  (my  Okidata  port)  or  the 
320Q. 

Be  sure  the  converter  is  wired  cor- 
ectly.  A  safe  check  to  make  is  to  apply 
power  with  no  IC’s  in  their  sockets;  see  if 
+5V  and  ±12V  are  where  they  should  be. 
Install  the  IC’s  when  it  looks  like  the 
smoke  test  will  be  a  happy  one. 

Set  the  baud-rate  switches  to  1200 
baud:  SI -a,  -b,  and  -c  should  all  be  open. 
Set  the  other  switches  for  the  format  I 
indicated  earlier:  S2-a  closed  for  1  stop 
bit,  S2-b  and  S2-c  open  for  8  bits/char¬ 
acter,  S2-d  can  be  open  or  closed  because 
S2-e  is  set  open  for  no  parity.  Table  II 
(page  35)  shows  all  the  possible  baud-rate 
selections;  Table  III  (page  35)  indicates 
how  I  set  SI  and  S2  for  my  system. 

Connect  the  serial -data  cable  (leave 
the  parallel  cable  off  for  now)  and  apply 
power.  Check  with  your  oscilloscope  on 
pin  17  of  the  UART  to  see  if  the  clock  is 
present.  Check  pin  3  on  the  DB-25  con¬ 
nector:  it  should  be  -12V  if  you  haven’t 
sent  anything  down  the  line  yet.  Pin  4 
should  be  -12V  to  indicate  that  the  port 
is  ready  to  take  data. 

If  it  appears  everything  is  ready  to  go, 
send  some  data  to  the  converter.  The  sim¬ 


plest  data  to  check  with  the  scope  is  a 
square-wave,  and  you  can  get  that  by 
sending  a  “U”  to  the  port.  Assuming 
you’ve  connected  into  what  your  operat¬ 
ing  system  takes  as  the  printer  port,  do 
a  simple  BASIC  program  like  this: 

100  LPRINT  “U”; 

200  GOTO  100 

300  END 

You  should  see  the  data  coming  in  on  pin 
3  one  character  at  a  time,  each  separated 
from  the  next  by  about  30  msec.  If  you 
see  a  square-wave  with  no  breaks  between 
characters,  then  you  know  that  the  RTS 
line  (or  whatever  busy  line  you’re  using) 
is  not  causing  the  CPU’s  UART  to  wait. 
Each  of  the  characters  should  be  8.3  msec, 
total  time  and  be  an  alternating  sequence 
of  +12 V  and  -12V  pulses.  If  you  observed 
the  proper  handshaking,  you  can  be  sure 
that  the  computer  and  the  converter  are 
at  least  talking  with  each  other.  While  the 
“U”  is  still  being  sent,  look  at  the  strobe 
output  (a  logic  probe  with  memory  is 
probably  the  easiest  to  check  with).  Did 
it  catch  a  pulse?  If  not,  see  if  you  catch  a 
pulse  back  at  the  UART  pin  19.  If  not 
there  either,  be  sure  that  RDAV*  on  pin 
18  is  not  being  held  low  for  some  reason. 

Check  the  parallel  output  lines  with 
the  scope  or  logic  probe.  You  should  see 
alternating  high  and  low  levels  when  you 
look  from  one  pin  to  the  next.  When  you 
look  at  an  individual  pin,  however,  the 
logic  level  should  not  change  (except 
perhaps  once  every  132  characters  if  the 
system  puts  a  CR/LF  in  automatically). 
If  you  find  that  the  data  lines  are  rattling 
around  in  a  somewhat  random  fashion, 


probably  the  baud  rate  is  not  matched  to 
what  the  CPU  is  sending.  Try  other  rate 
combinations  or  get  an  accurate  fre¬ 
quency  check  of  what  the  UART  is  get¬ 
ting  on  pin  17. 

If  you  got  this  far,  you  probably 
have  a  working  converter  and  you’re 
ready  to  hook  up  the  printer  or  whatever 
you  want  to  put  on  the  parallel  port.  Be 
sure  that  it  has  a  +5V  high-true  line  com¬ 
ing  back  for  handshaking;  if  your  device 
is  low-true,  skip  around  the  7400  inverter 
in  the  diagram.  If  you  intend  to  have  no 
handshaking  at  all,  adjust  the  resistor  and 
capacitor  on  pins  6  and  7  of  the  74123  so 
that  the  data  speed  is  acceptable  for 
whatever  device  you  have  connected  to 
the  parallel  port. 

Operation 

Once  the  converter  has  been  tested 
and  is  running  properly,  it  should  need  no 
further  attention.  I  leave  it  plugged  into 
the  320Q  port  until  I  want  to  use  the 
Selectric.  Then  I  tell  the  operating  system 
that  my  printer  is  on  320  rather  than 
340.  At  that  point,  I  treat  it  no  differently 
than  I  would  the  Okidata.  If  I  can’t  get 
back  to  the  operating  system  conven¬ 
iently,  I  can  always  just  swap  serial  data 
cables. 

Conclusions 

Overall,  I  would  say  that  the  project 
has  been  an  enjoyable  experience  for  me. 
I’ve  been  very  pleased  with  the  converter’s 
operation  —  it’s  everything  I  hoped  it 
would  be.  There  are  only  a  few  minor 
details  that  I  might  change  if  I  were  to 
build  it  over.  One  change  might  be  to  put 


Table  1 

Parts  List  for  Serial 

-To-Darallel  Board 

IC1 

BR -1941 -00  Western  Digital  Baud- Rate  Clock  v 

SI 

4-Pos.  DIP  SPST  Switch 

IC2 

AY3-1014 

General  Instruments  UART 

S2 

5-Pos.  DIP  SPST  Switch 

IC3 

7430 

8-input  NAND 

S3 

SPDT  PCB  MTD  Slide  Switch 

IC4 

7400 

Quad  2-input  NAND 

S4 

SPST  PCB  MTD  Slide  Switch 

IC5 

7404 

Hex  Inverter 

IC6 

MC1489 

Line  Receiver 

XI 

5.0688  MHz  Crystal  (wire  leads,  series  resonant, 

0  -  70° C,  ±0.01%,  R,  <  5012  ) 

IC7 

74123 

Dual  Monostable 

IC8 

MC1488 

Line  Driver 

J1 

Male  4-Contact  Power  Plug  (Molex  Series  6373, 

No.  22-11-2042) 

D1 

IN914  or  IN4148  Diode 

J2 

Female  DB-25,  PCB  MTD,  Right  Angle 

(Cannon  DBP-25-SAA) 

R1,R2 

5- Resistor  SIP  4.7K,  Bournes  4306R- 101  -472 

R3,R6,R7 

10K,  %W 

5  each 

14-Pin  Sockets  (Solder-Tail) 

R4,R5 

4.7  K,  ’AW 

1  each 

16-Pin  Sockets  (Solder-Tail) 

Cl 

0.005  Disk  Cap  100  V 

1  each 

18-Pin  Sockets  (Solder-Tail) 

C2 

560  pF  Sil 

Mica 

1  each 

24-Pin  Sockets  (Solder-Tail) 

C3 

3.3  f/F  Tantalum  15V 

1  each 

PC  Board  with  34 -Pin  Card- Edge  Connector 

C4,C5,C6 

0.01  Disk 

100V 

34 

4.?6 
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Table  II 

Baud -Rate  Switch  Settings 


Switch  SI 

Baud 

d 

c 

b 

a 

Rate 

X 

X 

X 

X 

50 

X 

X 

X 

0 

75 

X 

X 

0 

X 

110 

X 

X 

0 

0 

134.5 

X 

0 

X 

X 

150 

X 

0 

X 

0 

300 

X 

0 

0 

X 

600 

X 

0 

0 

0 

1200 

0 

X 

X 

X 

1800 

0 

X 

X 

0 

2000 

0 

X 

0 

X 

2400 

0 

X 

0 

o 

3600 

o 

0 

X 

X 

4800 

0 

0 

X 

0 

7200 

0 

0 

0 

X 

9600 

0 

0 

0 

0 

19200 

in  a  switch  to  disable  the  pseudo-busy 
circuit  so  it  wouldn’t  hold  up  a  full-speed 
printer.  I  drew  S4  into  the  circuit  where  I 
would  probably  put  it.  A  major  modifica¬ 
tion  to  consider  would  be  to  increase  the 
scope  of  the  project  by  connecting  up  the 
other  half  of  the  BR1941  to  the  transmit¬ 
ter  half  of  the  UART,  thereby  being  able 
to  send  different-speed  serial  data  back 
to  the  CPU.  If  you  have  the  need  to  con¬ 
vert  parallel  data  to  serial,  this  might  be 
worth  investigating. 

As  it  turned  out,  getting  the  Selectric 
in  operation  was  really  quite  easy  .  .  . 
once  I  had  my  converter  box  built.  Being 
able  to  simply  plug  in  the  utility  box 
made  a  world  of  difference  in  making  a 
smooth-running  system. 


Note:  "X"  means  switch  closed, 
"O"  means  open. 


For  those  of  you  who  do  not  wish  to  put 
all  this  together  for  yourself,  Mr.  Wilcox's 
converter  is  available  in  various  stages  of 
completeness  (from  the  PC  board  only,  to 
an  assembled  and  tested  unit,  minus  case 
and  power  supply)  from  Micro  Resources 
Inc.,  9064  Loreleigh  Way,  Fairfax,  Virginia 
22031.  Contact  them  for  details. 
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Table  III 

Example  Setting  for  SI  and  S2 

1200  baud 

1  stop  bit 

8  bits/character 
No  parity 

SI 

on 

off 

a 

• 

open 

b 

• 

open 

c 

• 

open 

d  • 

closed 

S2 

on 

off 

a  • 

closed 

1  stop  bit 

b 

• 

open 

8  bits/char. 

c 

• 

open 

8  bits/char. 

d 

• 

open 

not  in  use* 

e 

• 

open 

no  parity 

*Can  be  open  or  closed  with  no  parity 
select. 
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McWORDER 

A  Tiny  Text  Editor 


I  am  writing  this  article  with  a  5  4- line 
(without  comments)  word  processor. 

I  find  that  it  is  nearly  as  much  fun  to 
use  as  it  was  to  write.  1  call  this  editor, 
for  obvious  reasons,  McWORDER.  The 
source  listing  (pages  38-42)  is  written  for 
the  TRS-80  Model  II,  though  it  should 
not  be  too  difficult  to  convert  it  for  other 
machines.  The  program  is  not  yet  finished. 
The  block -handling  subroutines  in  the 
listing  are  not  installed. 

McWORDER  functions  in  two  modes, 
insert  and  change.  The  insert  mode  is 
indicated  by  a  steady  cursor  and  the 
change  mode  by  a  flashing  cursor.  In  the 
insert  mode,  printable  characters  are 
inserted  in  the  text  at  the  cursor  position. 
The  text  separates  to  accommodate  them 
and  words  overfowing  the  line  length  are 
gathered  in  a  new  line. 

The  cursor  movements  available  are: 
left,  right,  up,  and  down.  In  the  change 
mode  all  moves  stay  within  text  bounds. 
In  the  insert  mode,  “cursor  up”  creates 
a  new  line  when  the  cursor  is  on  the  first 
line,  and  the  remaining  cursor  moves  may 
position  the  cursor  one  character  position 
beyond  the  last  character  of  a  line.  The 
text  will  scroll  up  or  down  as  required 
by  the  cursor  moves. 

A  control  code  deletes  a  character 
at  the  current  cursor  position  and  the 
current  line  closes  up  behind  it.  If  the 
cursor  is  at  the  beginning  of  a  line  and  the 
line  is  empty,  the  line  will  be  deleted  and 
the  text  will  close  up.  All  text  changes  are 
shown  on  the  screen  because  the  print  sub¬ 
routine  always  prints  what  is  in  the  text. 
Even  scrolling  uses  the  print  subroutine. 
There  is  no  separate  scrolling  subroutine. 
Action  is  the  same  in  bc^h  modes. 

Backspace  replaces  the  previous 
character  by  a  space  and  moves  the  cursor 
one  character  left  when  in  the  change 
mode.  When  the  cursor  is  at  the  beginning 
of  a  line,  backspace  erases  the  last  charac¬ 
ter  of  the  previous  line.  In  the  insert 
mode,  backspace  deletes  the  previous 
character  and  the  current  line  closes  up. 
If  the  cursor  is  at  the  beginning  of  a  line, 
and  if  the  line  is  empty,  backspace  deletes 
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the  line,  the  text  closes  up,  and  the  cursor 
is  positioned  just  after  the  last  character 
of  the  previous  line. 

Carriage  return  puts  the  cursor  at  the 
beginning  of  the  next  line.  In  the  insert 
mode,  the  next  line  is  a  new  line. 

There  are  control  codes  to  output 
the  text  to  the  printer,  save  the  current 
text  to  disk,  and  load  a  text  file  from 
disk. 

Finally,  there  are  control  codes 
specific  to  the  Model  II  that  are  used  by 
the  subroutines.  1  turns  on  the  blinking 
cursor,  2  turns  the  cursor  off,  4  turns  on 
the  steady  cursor,  23  clears  to  the  end  of 
the  line,  and  24  clears  to  the  end  of  the 
screen. 

The  data  structure  used  for  the  text 
is  a  doubly  linked  list  whose  pointers  are 
in  separate  arrays  L(. )  and  R( . ).  I  have 
arranged  that  the  list  be  circular  with  the 
left  link  of  the  first  line  pointing  to  the 
last  line  and  the  right  link  of  the  last  line 
pointing  to  the  first  line.  L(0)  and  R(0) 
contain  the  locations  of  the  first  and  last 
lines,  respectively.  All  text  is  constrained 
to  have  at  least  one  line.  New  text  begins 
with  one  empty  line  and  all  pointers 
point  to  this  empty  line. 

My  purpose  in  writing  this  editor  had 
been  to  familiarize  myself  with  handling 
linked  lists.  However,  it  turned  out  that 
the  most  challenging  problem  was  design¬ 
ing  efficient  control  structures  (well- 
chosen  and  positioned  IF  .  .  .  THENs). 
I  am  still  studying  how  best  to  handle 
them. 

Writing  McWORDER  has  been  a  frus¬ 
trating,  excruciating,  exasperating  delight. 
I  hope  that  DDJ  readers  will  find  parts  of 
the  editor  useful  for  other  editing  tasks 
and,  just  maybe,  will  be  inspired,  as  I 
have  been,  to  modify  and  improve  upon 
the  editor  —  a  labor  of  love  possible  only 
when  commented  source  code  invites  the 
user. 


(Listing  begins  on  page  38) 
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McWorder  Listing  (Text  begins  on  page  36) 


10  '  MCWORDER:  A  TEXT  EDITOR 
20  ' 

30  ’  TEXT  IS  HELD  IN  STRING  ARRAY  7 S ( .  ) 

40  'LINKS  ARE  HELD  IN  L( .  )  AND  R( .  ) 

50  ’  L  (0)= INDEX  OF  FIRST  LINE,  R(  0 )  *  INDEX  OF  LAST  LINE. 

60  •  N=  INDEX  OF  CURRENT  LINE. 

70  * 

80  1  INITIALISE  EDITOR  (RO,CO)=TEXT  SCREEN  DIMENSIONS 
90  • 

100  CLEAR  20672  *.  DEF  1 NT  A-Z:RO=24:CO=80  ‘.DIM  T$(100),A(2-0), 
L(ioo),R(ioo) :s=o :R=5:c=o 

110' 

120  1  2 8= CURSOR  LEFT;  2 9= CURSOR  RIGHT;  00= CURSOR  UP; 

3 1  =  CURSOR  DOWN 

130  ’  I  =  TOGGLE  INSERT  MODE;  2=DELETE  CHAR;  8= BACKSPACE; 

13=  CARR  1 A GE  RETURN 

140  '  16=  OUTPUT  TEXT  TO  PRINTER;  4=SAVE  TEX 7  TO  DISK; 

1 2 =NEW  TEXT  OR  LOAD  TEXT 

150  ' 

160  DATA  28,29,30,31,1,2,8,13,16,4,12 
170  FOR  1=1  10  11 : READ  X : D$ =D$+ CHRS ( X ) : NEX1  1 
180  ' 

190  ’  GET  TEXT  FROM  DISK  OR  WRITE  NEW  TEXT 
200  ’ 

210  GOSUB  1380 
22  0  ' 

23  0  ’  GET  CHARACTER  FROM  KEYBOARD  AND  PROCESS  17 
240  ‘ 

250  PRlNli(R.C) , ; : A$=1NPUT$( 1 ) : IF  A$>CHR$ ( 31 )  THEN 
GOSUB  1050: GQ1 0  250 

260  ON  1 NSTR ( D$ , AS )  GOSUB  750,800,850,910,960,1000, 

1160, 1220 , 1270 , 1330 , 1380 
270  GOTO  250 
280  ’ 

290  1 - -  SUBROUTINES - 

300  ’ 

310  '  INSERT  NEW  LINE  BS  AFTER  LINE  INDEXED  N 
320  ' 

330  IF  S  THEN  T=A(S):S=S-1  ELSE  T=M:M=M+1 
340  1$(T)=B$:1F  N  =  R ( 0  )  THEN  R(0)=T 
350  L(T)=N:R(1)=R(N):L(R(1))=T:R(N)=T : RETURN 
360  * 

37  0  ’  INSERT  NEW  LINE  BS  BEFORE  LINE  INDEXED  N 
380  * 

390  IF  S  THEN  T=A(S):S=S-1  ELSE  T=M:M=M+1 
400  T$(1)=B$:1F  N  =  L ( 0  )  THENL ( 0  )  =T 

410  R(1  )=N:L(T)=L(N)  :R(L(1  )  )=T  :  L  (  N  )  =  1  :  RETURN  (Continued  on  next  page) 
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Listing  (Listing  continued,  text  begins  on  page  36) 

420  ’ 

43  0  ’  DEL  ETE  LINE  INDEXED  F 
440  ’ 

450  IF  F  =  R  (  0  >  THEN  IF  F  =  L(0)  THEN  RETURN  ELSE  R(0)  =  L(F)  ELSE 
IF  F=L( 0 )  THEN  L(0)=R(F) 

460  S=S+i :A(S)sF:R(L(F) )=R(F) :  L  (  R  (  F  ) ) *L ( F ) : RETURN 
47  0  * 

480  'DELETE  LINES  BETWEEN  LINE  INDEXED  F  AND  LINE  INDEXED 
FI 

490  ’ 

500  1«F:1F  F  1  =R  l  0  )  1  HEN  R(0)*L(F) 

510  S  =  S+  l:A(S)=T:IF  T  =F 1  1  HEN  R(L(F) )  =  R  (  F 1 ) :L(R(F1 ) )=L(F) : 
RETURN 

520  T  =R( T ) :GOTO  510 
530  ' 

54  0  'MOVE  BLOCK  START  INDEX  F,  END  INDEX  FI,  TO  AFTER  LINE 
INDEXED  N 

550  ' 

560  IF  N  =  R ( 0  )  THEN  R(0)«*F1  ELSE  IF  F1=R(0)  1  HEN  R(0)=L(F) 

570  IF  F  =  L  (  0  )  ‘I  HEN  L(0)=R(F1) 

580  RiL(F))=R(Fl):L(R(Fl))=>L(F):L(R(N))=Fl:R(Fl)=R(N): 

R  (  N  )  =F  :  RET  IJRN 

590  ’ 

60  0  'MOVE  BLOCK  START  INDEX  F,  END  INDEX  FI,  TO  BEFORE  LINE 
INDEXED  N 

610  1 

*20  IF  N  =  L ( 0 )  THEN  L(0)=F  ELSE  IF  F  =  L(0)  THEN  L(0)=R(F1) 

630  IF  f 1 =  R ( 0  )  THEN  R(0)=L(F) 

640  R(L(F ) )=R(F1 ) : L ( R ( F 1 ) )=L(F) : R ( L ( N ) )=F:L(F)=L(N) : 

L(N)«=F1  *.R(F1  )  *=N  :  RE'I  URN 

65  0  ’ 

660  '  RR I  NT  TEXT  FROM  SCREEN  LINE  B  TO  END  OF  TEXT  OR  SCREEN 
67  o  'STARTING  I  ROM  LINE  INDEXED  T 
680  * 

690  PR1NT@(B, 0 ) ,CHR$(2) ;  :F0R  X=B  TO  R0- 1 : PR 1  NT  0 ( X , 0 ) , CHR$ ( 23 ) ; 

isn ) ; 

700  IF  1 =R ( 0  )  THEN  PR  1  NT CHRS ( 24 ) ; : PR  1  NT @ ( R , C ) , 

CHR$  (  4  +  3  *  (  I  =  0  )  )  ;  ‘.RETURN 

71o  I =R( T ) : NEXT  X : PR1NT8X R , C ), CHR* ( 4+3 *( 1 =0 >);: RETURN 

72  0  ’ 

73  0  '  CURSOR  LEFT 
740  * 

750  IF  C>0  THEN  CeC- 1 : RETURN  ELSE  IF  R>5  THEN  R=R-1  ELSE 

IF  NoL(O)  THEN  FS  =  L(N)  :B  =  5:TcFS:  GOSUB  690  ELSE  RETURN 
760  N  =  L(  N  )  :  C  =  LEN(  T$(N)  )  +  (  LEN(  T  5  (  N  )  )>0  AND  1  =  0)*.RETURN 
77  0  • 

780  ’  CURSOR  RIGHT 
790  ’ 
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800  If  C<LEN(T$(N) )+( 1=0 )  THEN  C«C4 1 : RETURN  ELSE 
IF  N=R ( 0 )  THEN  RETURN 

810  N=R(N):lf  R=RO-l  THEN  B=5:FS=R(FS) : T  =  F S : C  =  0 : 

GOTO  690  ELSE  R  =  R4 1 : C  = 0  I  RETURN 

820  * 

83  0  '  CURSOR  UP 

840  * 

850  IF  R>5  THEN  R  =  R-  1  ’.  N  =  L  (  N  )  : 

T  =  LEN(T$(N)  )  +  (  1  =  0  AND  LEN(  T$  ( N )  )>0  )  C  =  C+  (  C-T  )  *  (  C>T  )  : 
RETURN 

860  IF  N=L ( 0 )  THEN  IF  1  THEN  B$  =  "" : GOSUB  390  ELSE  RETURN 
870  8i5: FS  =  L ( N ) : T  =  FS : GOSUB  690:N  =  L(N): 

T  =  LEN(T$(N) )  + ( 1  =  0  AND  LEN ( T  $ ( N) ) >0 ) : C  =  C+ ( C- T ) * ( C> T  )  : 
RETURN 

880  1 

89  0  '  CURSOR  DORN 
900  ' 

910  IF  N=R ( 0 )  THEN  RETURN  ELSE  IF  R=RO-l  THEN  B=5 ! FS  =  R ( FS ) : 

T  =  FS : GOSUB  690  ELSE  R  =  R+1 
920  N  =  R(N)  :T  =  LEN(T$(N) )  +  ( 1  =  0  AND  LEN ( T S ( N  )  ) > 0 ) : 
C=C4(C-T>*(C>T) : RETURN 

930  1 

940  •  toggle:  INSERT  MODE 
950  ’ 

96  0  I  =  -  (  I  <1  ):  PRINT®  (  R  ,  C  )  ,  CHR$  (  4  +  3M  1  =  0));  ’.RETURN 

97  0  * 

98  0  'DELETE  CHARACTER  AT  CURSOR 
990  ' 

1  000  IF  T  $  ( N  )  = " "  THEN  F  =  N:IF  NoR(0) 

THEN  N  =  R(N) ’.GOSUB  450  :  B  =  R  :  T  =  N  :  GOTO  690  ELSE  GOSUB  750  : 
GOTO  450 

ioio  c=C4(len(tkn)  )  =  C) : 

T$(N)=LEFT$(T$(N) ,C)+MID$(T$(N) ,C42)  : 

PRINT  @ ( R , C ) , CHR$(23) ; MID$ ( T$ ( N ) , C4 1 ) ; : RETURN 
1020  1 

1  03  0  'CHANGE  OR  INSERT  CHARACTER 
1040  ' 

1050  IF  1=0  THEN  IF  T$(N)>""  THEN  M IDS ( T % ( N ) , C4 1 ) = A$ : 

PRINT8(R,C) ,CHR$(2) ;A$;CHR$( 1 ) ; :GOTO  800  ELSE  RETURN 
1060  IF  T  $ ( N )  =  " "  THEN  T $ ( N ) = A$ : PR  I  NT 8 ( R , C ) , A$ ;  : GOTO  800 
1070  IF  L£N(T$(N) ) <LL  THEN 

T$(N)=L£FT$(T$(N)  lC)4A$4MID$(T$(N)fC4l)’. 

PR  I  NT  @ ( R , C ) , CHR$ ( 2 ) ;MlD$(T$(N),C4l) ;CHR$(4) ;  : GOTO  80  0 
1  0  80  L  =  LL+ 1 : C$  =  L£FT $ ( T$ ( N ) ,C)4A$4MID$(T$(N),C4l): 

FOR  U=1  TO  LEN ( C$ ) 

1090  IF  INSTR(RIGHT$(C$ ,J) , "  ")=0  THEN  NEXT  J:J=1 
1100  TS(N)=LEFT$(C$ ,L-J) :BS  =  RIGHT$(C$ . J-l  )  : IF  C>L-J-1  THEN 
FF= 1 : C=C-L+ J 


(Continued  on  page  42) 
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McWorder  Listing  (Listing  continued,  text  begins  on  page  36) 


1110  IF  FIoN  THEN  GOSUB  330:FI=N  ELSE  IF  NoR(O)  THEN 
T  $ ( R ( N ) ) =  L£FT  $  (  B  $  4  "  " 4 T $ < R ( N ) ) , LL  )  ELSE  GOSUB  330: 

T  $ ( R ( N ) ) =B$ 

1120  B=R:T=N:GOSUB  690: IF  FF  THEN  FF=0:GOTO  910  ELSE  600 
1130  * 

1140  'BACKSPACE 
1150  ’ 

1160  IF  U0  THEN  1180  ELSE  IF  C  THEN  GOSUB  750: 

GOTO  1000  ELSE  IF  T$(N)>""  THEN  GOSUB  750:GOTO  1000 
1170  F  =  N  :  IF  NoR(0)  THEN  N=R ( N )  :  GOSUB  450  :  B  =  R  :  T  =  N  :  GOSUB  690: 

GOTO  750  ELSE  GOSUB  750:GOTO  450 
1180  GOSUB  750:1F  T$(N)>""  THEN  MIDI ( T $ ( N ) , C+ 1 , 1 ) »"  " : 

PRINTER  ,C)  ,  "  RETURN  ELSE  IF  N=L<0)  THEN  RETURN  ELSE 
1  180 
1190  ’ 

1200  ' CARR 1 A GE  RETURN 
1210  ' 

1220  IF  1=0  THEN  C^O:GOTO  910 

1230  B$="":GOSUB  330  :  B  =  R  :  T  =  N  :  GOSUB  690:GOTO  910 
1240  ' 

1250  'OUTPUT  TEXT  TO  PRINTER 

1260  1 

1270  T  =  L ( 0  ) 

1280  LPR I  NTT  $ ( T  )  :  IF  T  =  R(0)  THEN  RETURN 
1290  T  =  R ( T ) : GOT 0  1280 
1300  * 

1310  'SAVE  TEXT  TO  DISK 
1320  ’ 

1330  PRINT@0,CHR$(23); "TEXT  NAME” ;: INPUT  F$ : 0PEN"0" , 1 , F$ : 

T=L ( 0 ) :PRINT#1 , LL 

1340  PRINTtfl ,T$(T) : IF  T=R(0)  THEN  CLOSE : RETURN  ELSE  T  =  R ( T ) : 

GOTO  1340 
1350  * 

1360  'LOAD  TEXT  EROM  DISK  OR  START  NEW  TEXT 
1370  ’ 

1380  fi=o:s=o:r=5:c=o:print@o,chr$(23) ; : 

1 NPUT "TEXT  NAME  ( <CR>  IF  NEW  TEXT ) " ; Q$ : I F  Q$=""  THEN 
1  420 

1390  OPEN'TM  ,  Q$  :  QS  =  :  INPUT#1  ,  LL  :  FOR  T=1  TO  101 

1400  IF  EOF ( 1  )  THEN  R(0)=T-1 :L( 0)  =  1 :L( 1 )=R(0) :R(R( 0) )  =  1 :N=1  : 

M  =  R1 0 ) 4 1 : F s  =  N : I  =  0:B  =  5:T=1 : CLOSE: GOTO  690 
1410  L I NE I NPUT #1 ,  T$ ( T ) : L  <  T ) =T- 1 : R( T ) =T+ 1 : NEXT  T : CLOSE : RETURN 
1420  CLS:PRINT80 , ; : 1NPUT"L1NE  LENGTH" ; LL : IF  LL>CO  THEN 
LL=CO:PR1NT@0 , "CHOPPED  TO" ; CO; "CHARACTER  LINE" 

143  0  T$( l  )  =  "” :N=l :M=2:FS= i:l  =  i:L(0)  =  i:R(0)  =  l:L(l)  =  l:R(l)  =  l: 
PR  I  NT CHR$ ( 4 ) ;  : RETURN 


End  Listing 
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Fast  Matrix  Operations 

In  Forth,  Part  III 


This  final  part  of  the  series  uses  the  ma¬ 
terial  presented  in  the  first  two  parts  to 
build  some  applications.  In  those  earlier 
installments,  the  author  used  a  word, 
IN#,  which  allows  free-format  numeric 
input.  The  Forth  code  for  this  word  is 
provided  in  Screen  No.  129  (page  47). 
While  it  is  not  part  of  Poly  forth,  it  was 
written  for  the  author  by  Forth  Inc.  and 
is  printed  here  with  the  permission  of 
Forth  Inc.  -  Ed. 


In  the  last  two  parts  ( DDJ  Nos.  80  and 
81 ),  I  presented  some  Forth  words  to 
perform  matrix  operations  with  syntac¬ 
tically  simple  phrases.  In  this,  the  last 
installment,  these  words  will  be  used  in 
some  application  programs  to  demon¬ 
strate  the  merits  of  such  an  extension  to 
the  Forth  language.  Also,  these  programs 
were  selected  to  be  interesting.  It  is  hoped 
that  incredulous  readers  will  be  tempted 
to  duplicate  some  of  these  programs  in 
their  favorite  language  and  thereby  con¬ 
vince  themselves  of  Forth’s  potential 
superiority  as  a  number  cruncher. 

Image  Processing 

Matrix  operations  are  used  extensive¬ 
ly  in  the  field  of  Digital  Image  Processing. 
This  usage  is  not  at  all  surprising  when 
one  considers  that  a  digital  image  is,  itself, 
a  matrix.  Screens  294  and  296  (pages  48- 
50)  contain  a  program,  OUTPIC,  that 
prints  a  “poor  man’s  grey  level  picture” 
on  the  IBM  (Epson)  printer  If  we  store  a 
picture  in  matrix  A  so  that  the  value  of 
each  matrix  element  represents  the  rela¬ 
tive  brightness  of  a  pixel,  the  phrase, 
PRINT  OUTPIC,  will  print  out  the  pic¬ 
ture  by  using  ASCII  characters  with  over¬ 
strikes  to  achieve  32  brightness  or  grey 
levels.  Figures  la,  lb,  and  lc  (page  45) 
were  produced  by  OUTPIC.  Figure  la  is 
titled  “Smiley  Face”  and  Figure  lb  is 
titled  “Snow  Storm.”  These  images  were 
chosen  because  they  are  easily  generated. 

Consider  the  following  problem: 
Given  two  pictures,  Figures  la  and  lb, 


by  Steven  A.  Ruzinsky 


Steven  A.  Ruzinsky,  2110  South  Austin 
Boulevard,  Cicero,  Illinois  60650. 


produce  a  third  picture  (Figure  lc), 
which  has  the  image  of  la  and  the  grey 
level  histogram  of  lb.  In  other  words, 
how  do  we  rearrange  the  pixels  of  lb  to 
make  lb  look  like  la?  In  the  simple 
Rosenfeld  method,  the  darker  pixels  of 
lb  are  given  priority  assignment  to  the 
locations  of  the  darker  pixels  of  la.  Gen¬ 
erally,  in  this  method,  a  random  choice  is 
made  in  the  assignment  of  pixels  of  equal 
grey  levels,  producing  a  blotchy  result.  In 
the  program  of  screens  297  and  298 
(pages  50-51),  MATCH-Al-to-A2,  prior¬ 
ity  assignment  of  pixels  with  equal  grey 
level  values  is  made  on  the  basis  of  their 
closeness  to  other  dark  pixels.  Figure  lc 
is  the  result  of  this  histogram  matching 
technique. 

Least  Squares  Regression 

One  of  the  most  interesting  and  use¬ 
ful,  applications  of  matrices  is  Least 
Squares  Regression  analysis.  Here,  a  func¬ 
tional  relationship  between  a  dependent 
variable,  y,  and  n  independent  variables, 
Xi,  x2,  ....  xn,  is  modeled  by  the  fol¬ 
lowing  equation: 


(1)  y  =  ajX!  +  a2x2  +  . . .  +  anxn  +  E 


in  matrix  notation:  y  =  aTx  +  E 


rxr 

where :  a  = 

a2 

,  X  = 

x2 

an 

—  _ 

*n 

and  E  =  Error 


The  term,  E,  can  be  considered  to  repre¬ 
sent  everything  that  influences  y  that  has 
not  been  accounted  for  by  x.  In  practice, 
the  factors  of  E  are  usually  unobservable; 
therefore,  the  equation  actually  used  to 
approximate  or  estimate  y  from  measured 
values  of  x  is: 


(2)  y  =  ajX!  +  a2x2  +  .  .  .  +  anxn 


or  y  =  aTx 


Hence,  it  is  desirable  to  find  a  such  that 
the  error,  E,  is  in  some  way  minimized.  In 
least  squares  regression,  sample  values  of 
x  and  y  are  analyzed,  and  ji  is  found  such 
that  the  mean  squared  value  of  E  is  a 
minimum.  There  are  several  algorithms 
for  performing  least  squares  regression. 
Implementations  of  two  such  algorithms 
are  presented  here  in  Forth. 

The  first  is  a  “batch  ”  least  squares 
algorithm,  so  called  because  all  of  the 
data  is  processed  at  one  time.  The  matrix 
equation  describing  the  algorithm  is: 


(3)  a  =  (XTX)'‘  XTy 


where:  X 

Xll 

X21 

X12 

x22 

•  •  •  xln 
...  X2n 

•  •  •  x3n 

Xri 

Xf2 

• •  •  Xrn 

an  d  y  = 

y~ 

y  2 

yr 

Here,  the  subscript,  i,  of  Xjj  and  yj  refers 
to  different  sets  of  measurements,  r  in 
number,  and  the  subscript,  j,  of  x;j  refers 
to  the  different  variables,  n  in  number.  It 
is  essential  that  r  >  n. 

What  do  you  do  if  you’re  on  a  de¬ 
serted  island  with  your  computer  and  you 
need  a  12th  order  polynomial  approxima¬ 
tion  for  a  cosine  but  you  don’t  have  a 
handbook  to  look  it  up?  Well  obviously 
you  let  xi  =  1,  x2  =  x,  X3  =  x2,  x4  =  x3 
etc.  and  use  equation  (3)  to  find  a,  the 
polynomial  coefficients.  A  program  for 
doing  this  is  in  screen  301  (page  52).  A 
printout  of  the  results  is  given  in  Figure  2 
(page  46).  It  is  interesting  to  compare 
these  results  with  those  given  in  the 
Handbook  of  Mathematical  Functions  by 
Abramowitz  and  Stegun.  The  largest  or¬ 
der  polynomial  given  is  10th  order  and 
has  a  maximum  absolute  error  of  2.0E-9. 
Here,  my  12th  order  polynomial  resulted 
in  a  maximum  absolute  error  of  2. IE- 12 
—  not  bad  for  homebrew  polynomial 
approximations. 

In  the  preceding  example,  the  error, 
E,  represents  the  contribution  to  y  of 
higher  powers  of  x.  If  an  infinite  order 
polynomial  were  fitted  to  the  data,  E 
would  be  0,  and  ji  would  be  the  coeffi¬ 
cients  of  the  Tailor  series  expansion  for 
the  cosine.  Frequently  E  represents  ran¬ 
dom  factors.  The  program  given  in  screen 
300  (page  52)  is  similar  to  the  preceding 
except  a  random  number  has  been  added 
to  the  data.  This  program  plots  the  data 
with  its  polynomial  approximation.  The 
results  are  shown  in  Figure  3  (page  46). 

Next  comes  a  “sequential”  least 
squares  algorithm.  Let’s  say  we  have  a 
constant  input  of  data  and  we  always 
want  to  make  the  best  possible  estimate 
of  y  with  the  data  we  have.  As  we  receive 
new  data,  it  would  be  best  from  the  view¬ 
point  of  saving  both  speed  and  memory 
if  we  could  base  our  calculations  on  old 
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a  (  0,0)=  0.9999999999987197 

a  (  1,0)  =  -0.0000000000000006 

a  (  2*0)  =  -0.4999999999537521 
a  (  3,0)=  0.0000000000000042 

a  (  4^0)  =  0.0416666663880298 

a  (  5,0)  =  -0.0000000000000085 
a  (  6,0)  =  -0.0013888882583870 
a  (  7,0)=  0.0000000000000070 

a  (  8*0)=  0.0000248009073781 

a  (  9,0)  =  -0.0000000000000026 
a  (  10  ’  0  )  =  -0.0000002751960534 
a  (  11  ,  0  )  =  0.0000000000000003 

a  (  12 , 0  )  =  0.0000000019835358 

Maximum  Absolute  Error  = 

0.0000000000020661 

Figure  2. 

Coefficients  of  12th  order  polynomial 
approximation  to  cosine  function 
found  by  least  squares  regression  pro¬ 
gram  of  screen  301. 


results  and  new  data  rather  than  old  data 
and  new  data.  The  following  algorithm 
provides  a  method  for  doing  this: 

Pr-i  xr  xrT  Pr_! 

(4a)  Pr  =  P„  -  t— -T-p;_, 

(4b)  ar  =  ar.!+  Pr  xr  (yr  - xrT  ar_,  ) 

Here,  the  subscript,  r,  refers  to  the  rth 
successive  iteration.  xr  is  the  rth  measure¬ 
ment  of  x.  The  initial  value  of  Pr,  i.e.,  POJ 
should  be  set  equal  to  zl  where  z  is  the 
largest  number  your  computer  can  com¬ 
fortably  handle.  Pr  =  (XTX)_1  of  the 
batch  algorithm  and  is  therefore  an  nth 
order  square  matrix. 

Suppose  you  want  to  predict  tomor¬ 
row’s  stock  price  from  past  stock  prices. 
After  some  preconditioning  of  the  data 
you  may  be  able  to  model  the  relation¬ 
ship  as: 

(5)  xk  =  a,xk.i  +  a2xk.2  +  .  .  . 

.  .  .  +  anxk_n  +  wk 


Figure  3. 

Graph  of  scattered  data  with  polynomial  approxi¬ 
mation  produced  by  Program  in  screen  300. 
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Here,  xk  is  tomorrow’s  price,  xk_i  is 
today’s,  xk.2  is  yesterday’s,  etc.  wk  is  a 
random  number  and  therefore,  by  defini¬ 
tion,  unpredictable.  If  the  coefficients,  a, 
were  known,  you  could  predict  with 
error,  wk,  tomorrow’s  stock  prices  by 
using: 

(6)  xk  =  a,xk.1  +a2xk.2  +  .  .  . 

.  .  .  +  anxk.n 

In  case  you  haven’t  noticed,  equations  (5) 
and  (6)  are  just  special  cases  of  equations 
(1)  and  (2),  so  we  can  use  least  squares 
regression  to  find  the  coefficients,  a. 

In  the  programs  of  screens  302  and 
303  (pages  52-53),  a  signal  is  generated 
directly  from  equation  (5)  with  five  auto¬ 
regressive  parameters,  ai  =  0.6,  a2  =  -0.4, 
a3  =  -0.2,  a4  =  -0.3,  and  a5  =  -0.1.  A  bar 
graph  of  960  iterations  of  xk  is  given  at 
the  top  of  Figure  4  (page  46)  and  its 


estimate,  xk  is  shown  underneath.  The 
program,  DEMO,  in  screen  303  uses  the 
sequential  least  squares  algorithm  to  find 
a  from  [  xk  ] .  A  printout  of  the  results 
of  DEMO  is  given  in  Figure  5  (page  47). 

In  summary,  with  the  advent  of  nu¬ 
meric  co-processors,  particularly  those 
with  stack  architectures  -  e.g.,  the  Intel 
8087  and  80287  and  upcoming  Motorola 
68881  (complement  to  the  68000)  — 
Forth  is  potentially  the  best  high-level 
language  for  utilizing  their  speed. 

A  major  step  in  realizing  this  poten¬ 
tial  has  been  made  by  Forth,  Inc.  with 
their  use  of  the  8087  register  stack  as  an 
extra  Forth  stack  in  Polyforth  Level  2  for 
the  IBM  PC.  Hopefully,  this  article  has 
indicated  direction  for  further  develop¬ 
ment  of  this  potential.  By  extending  Forth 
to  include  words  similar  to,  but  not  iden¬ 
tical  to,  those  of  APL  (A  Programming 
Language),  Forth  can  provide  the  best 


combination  of  speed,  interactivity,  and 
programming  convenience. 

As  a  guideline  for  future  develop¬ 
ment  of  matrix  operations  in  Forth,  it  is 
recommended  that  the  Forth  words  be 
more  specialized  and,  hence,  less  versatile 
but  more  numerous,  than  those  of  APL. 
Tradeoffs  of  speed  for  error  checking, 
versatility,  and  compactness  should  be 
minimized.  The  importance  of  an  interac¬ 
tive  approach  in  number  crunching  can 
not  be  overemphasized,  and  speed  is 
necessary  for  interactivity. 

So  who  says  Forth  is  no  good  for 
number  crunching?  *»j 

(Listing  begins  below) 


10.  Iterations 

1000.  Iterations 

100000.  Iterations 

a  (0,0)  =  0.1233901268682028 

a  (  1  ,  0  )  =  -  0.1 24566609347851 7 
a  (  2 , 0  )  =  -  1 .2743755682353395 
a  (3,0)  =-0.5459890505070130 
a  (4,0)  =-0.2063259146671595 

a  (0,0)  =  0.6266869267910911 
a  (  1  ,  0  )  =  -0.4646612542696020 
a  (2,0)  =-0.1753721863446832 
a  (  3 , 0  )  =  -  0.30447907981 36833 
a  (4,0)  =-0.1227354803740424 

a  (  0 , 0  )  =  0.6002403624134816 

a  (  1  ,0  )  =-0.4029950413202153 
a  (2,0)  =-0.1984026117414880 
a  (3,0)  =-0.3019761820629188 
a  (  4 , 0  )  =  -  0.09996497074 15213 

100.  Iterations 

10000.  Iterations 

1000000.  Iterations 

a  (0,0)  =  0.3611617403734882 

a  (  1  ,  0  )  =  -0.2500877037073712 
a  (2,0)  =-0.1941419095476008 
a  (3,0)  =-0.3755920541195973 
a  (4,0)  =-0.1781407635452931 

a  (  0 , 0  )  =  0.6067 1 89034 1 8367 1 
a  (  1  ,  0  )  =  -0.4254754709960817 
a  (2,0)  =-0.1729774822474928 
a  (3,0)  =-0.3158399892817091 
a  (4,0)  =-0.1012047713266529 

a  (0,0)  =  0.6014009069329175 

a  (  1  ,  0  )  =  -  0.4002088620556101 
a  (  2 , 0  )  =  -  0.2003490862724384 
a  (  3 , 0  )  =  -  0.2999269894431592 
a  (  4 , 0  )  =  -  0.099 1 704866903059 

Figure  5. 

Estimates  of  autoregression  coefficients  of  signal  shown  in  Figure  4,  found  by  program  in  screens  302  and  303. 

Fast  Matrix  Operations  (Text  begins  on  page  44) 


(Screen  129  printed  with  the  permission  of  Forth  Inc.) 


129 

0  (  8087  Free  Format  Numeric  Input  by  Robert  Drap  of  Forth,  Inc.) 

1  CODE  RESCAN  (  a  -  a ’  )  O  POP  O  O  OR  0=  NOT  IF  1  POP 

2  PTR  U)  INC  4  #  I  SUB  THEN  NEXT 

3 

4  :  >SCAN  (  a  -  a’)  -1025  PTR  !  BEGIN  2DIGIT  RESCAN  DUP  Co) 

5  DUP  43  48  WITHIN  SWAP  58  =  +  WHILE  O  PTR  !  REPEAT  ; 


6 

7  : 

8 
9 

10 
11  : 
12 

13 

14  : 


SCAN  (  a  -  t)  >SCAN  DUP  Co)  DUP  32  -  IF  DUP  69  =  SWAP  101 

=  +  ?DUP  0=  IF  DROP  O  EXIT  THEN  +  >SCAN  C3)  32  - 
IF  O  EXIT  THEN  1  PTR  !  ELSE  2DROP  THEN  1  ; 

IN#  (  -  t)  (  -  r)  QUERY  32  WORD  DUP  SCAN  IF  NUMBER 
PTR  5)  0<  IF  >N  ELSE  PTR  5)  0=  IF  2>N  THEN  THEN  O 
ELSE  1  THEN  O  >IN  !  O  CNT  !  DROP  ; 

# I N  IN#  N>  ; 


(Continued  on  next  page) 
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Fast  Matrix  Operations  (Listing  continued,  text  begins  on  page  44) 


i94  LIST 

O  (  Subroutine! 


1 

0) 

79 

EMIT  ; 

1 ) 

•■7 

4) 

43 

EMIT  ; 

5) 

8) 

42 

EMIT  ; 

9) 

:  11) 

:  14) 

:  16) 

:  20) 

:  24) 

:  27) 

:  29) 
30)  BS 


10) 
10) 
10) 
19) 
19) 
26) 
175 
;  30) 


16)  19)  ; 
31)  7  30) 
21)  7  20 ) 
11)  7  10) 


BS  1) 
BS  4) 


BS  4)  ; 

BS  26)  ; 

EMIT  BS 
;  :  B) 

;  :  17) 

0  7  29) 

))  7  19) 
>)  7  9)  : 


by  OUTPIC 

) 

80 

80  m 

3 1  r*  i 

A 

80 

80  m 

atrix  B 

46 

EMIT 

5  ■ 

2) 

44 

EMIT 

% 

T 

)  45 

EMIT  ; 

1 1 1 

EMIT 

•I 

:  6 

)  48 

EMI 

T  » 

*  ? 

2 

7)  79 

EMIT  ; 

36 

EMIT 

5  ■ 

10 

)  35 

EMIT  ; 

2 

BS  8 

EMIT  ; 

12) 

10) 

BS 

2) 

?  ■ 

13) 

10) 

BS 

3)  ; 

17) 

10) 

BS 

5) 

BS  7 

)  ; 

:  15) 

10)  BS  6)  ; 

18) 

10) 

BS 

8) 

■  m 

5  ■ 

19) 

10) 

BS 

9  > 

21 ) 

19) 

BS 

2) 

?  • 

22) 

19) 

BS 

3)  ; 

25) 

19) 

BS 

5) 

n  ■ 

26) 

19) 

BS 

7)  ; 

:  23 

)  19) 

BS 

8) 

■  « 

!»  ■ 

28) 

27 

BS  27) 

* 

75  EMIT  ; 

: 

30) 

29) 

BS 

29) 

:  31 ) 

30)  BS 

6)  ; 

:  C) 

17 

)  ; 

?0)  ; 

:  1 

9) 

B) 

5  • 

20) 

C) 

i 

28) 

7  27 

)  7 

26 

)  7 

25) 

7  2J 

1) 

7  23) 

7  r7r? ) 

18) 

7  17 

r>  7 

16 

>)  7 

15) 

7  1‘ 

4) 

7  13) 

7  12) 

8)  7 

7)  7 

6) 

■> 

5)  7 

4) 

»  7 

7 

2)  7 

1 )  7  0 ) 

295  LIST 


transfers  the  addresses  from  the 


32  ARRAY  XX  : 
:  PRINT-GREY 
var iable  MIN 
variable  MAX 


FILL-XX  32  0  DO 
XX  ©EXECUTE  ; 

~  :  MIN!  MIN  '1 
~  :  MAX©  MAX  ©1 


SELECT-MAX -MIN  dim© 


(  Line  1  transfers  the  addresses  from  the  stack  to  array  XX, 
2  ARRAY  XX  :  FILL-XX  32  0  DO  I  XX  !  LOOP  ;  FILL-XX 
PRINT-GREY  XX  ©EXECUTE  ;  :  COMP  27  EMIT  51  EMIT  22  EMIT 

iriable  MIN  :  MIN!  MIN  !1  ;  :  MI  N©  MIN  ©1  ; 

triable  MAX  ~  :  MAX©  MAX  ©1  ;  ~  :  MAX!  MAX  !1  ; 

SELECT— MAX— MIN  dim©  n!  m!  0  0  A  ©1  FDUP  MIN!  MAX! 

n©  O  DO  m©  O  DO  I  J  A  ©1  FDUP 

MIN©  F<  IF  MIN'  ELSE  FDUP  MAX©  F>  IF  MAX! 
ELSE  FDROP  THEN  THEM  LOOP  LOOP  MAX©  MIN©  ; 
QUANTIZE  SELECT-MAX -M I N  F-  FDUP  F0=  NOT  IF  31.0  FSWAP  F/  ! 
n©  O  DO  m©  O  DO  I  J  A  DLIP  ©1  MIN©  F-  MAX©  F* 

N>  >N  !  2  LOOP  LOOP  ELSE  FDROP  THEN  [  7  3  A  e>;cl2  ; 
OUTPIC  is  the  poor  man’s  grey  level  picture. 

:  OUTPIC  I7!  A  QUANTIZE  m©  O  DO  n©  O  DO  J  I 
A  ©1  N>  PR I NT- GREY  LOOP 

13  EMIT  COMP  10  EMIT  LOOP  27  EMIT  64  EMIT  r 


OUTF'IC  i  = 
:  OUTP I C 


(Continued  on  page  50) 
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Fast  Matrix  Operations 


(Listing  continued,  text  begins  on  page  44) 


296  LIST 

U  (  Generate  smiley— face  -for  demonstrat  i  on  of  MATCH 

1 

2  VARIABLE  XO  VARIABLE  YO  VARIABLE  R  VARIABLE  U1  VARIABLE  U2 

3  :  CIRCLE  a!  U2  1  U1  R  !  YO  !  XO  !  U2  0  1+  U1  ©  DO  I  >N 

4  .0174533  Ft  FDUP  SIN  FSWAP  COS  R  ©  >N  Ft  N>  XO  3  + 

5  R  3  >N  F t  N>  YO  3  +  SWAP  a©  EXECUTE  LOOP  ; 

6:  Q.5A  '1  ;  j  W  1 . 0  A  !1  ;  :  7  .3  A  '1  ; 

7  :  SMILEY-FACE  C  ’  3  A  clr 


8 

39 

39 

35  0  360  C’3  f 

3  CIRCLE 

9 

39 

43 

1  0  360  C’3  W 

CIRCLE 

10 

49 

29 

1  0  360  C’3  W 

CIRCLE 

1 1 

29 

29 

1  0  360  C ’ 3  W 

CIRCLE 

12 

49 

29 

8  225  315  C’3 

Z  CIRCLE 

13 

29 

29 

8  225  315  C ’ 3 

Z  CIRCLE 

14 

15 

39 

^’5 

35  55  125  C’3 

Q  CIRCLE 

297  LIST 

O  <  Subroutines  Used  by  MATCH-A1 -to-A2  <  ) 

1 

2  :  B0  j  !  i  !  i  .0  ABS  i  1  j©  ABS  j!  i©  m3  <  NOT  IF  m3  2-  i  1  THEN 

3  j3  n3  <  NOT  IF  n0  2-  j  !  THEN  i3  .13  B  31  ; 

4  :  AVG-B  C’3  B  dim©  n!  m!  n3  O  DO  m3  0  DO  I  J  B3  I  1+  J  B3  F+ 

5  I  1-  J  B3  F+  I  J  1+  B3  F+  I  .J  1-  B3  F+  5.0  F/  I  J  B  !2 


6  LOOP  LOOP  C’3  B  ex cl 2  ; 

7  <  The  following  repeats  a.  modified  averaging  operation  on  ) 

B  (  matrix  B1  by  the  number  of  times  on  the  stack.  ) 

9  :  REPEAT-AVG-B  0  DO  AVG-B  LOOP  ; 

10  (  The  following  stores  sequential  numbers  from  0  to  mn-1  in  ) 

11  <  matrix  B1  starting  at  -CO, 03,  going  down  the  column,  then  ) 

12  (  to  tO, 13  and  down  etc.  ) 

13  :  STORE— INDEX— IN— B2  C ’ 3  B  di m3  *  0  DO  I  >N  I  0  B  !2  LOOP  ; 

14 

15 


298  LIST 


0  :  MATCH— A1 —to— A2  (  Histogram  Matching  Routine  ) 

1  C’3  A  C’3  B  1  1  — >  (  Transfer  A1  to  B1  ,  ) 

2  m3  2/  REPEAT-AVE— B  (  Repeat  averaging  operation  m/2  times.  ) 

3  . Ol  C’3  B  at  (  Divide  B1  grey  level  values  by  lOO.  ) 

4  C’3  A  C’3  B  A+  (  Add  A1  to  Bl.  ) 

5  C’3  A  rndA  (  Fill  A1  with  random  numbers.  ) 

6  1.0E— 12  C’3  A  at  (  Divide  A1  grey  levels  by  a  trillion.  ) 

7  C’3  A  C’3  B  A+  (  Add  A1  to  Bl.  ) 

8  STORE— INDEX— IN— B2  (  Store  sequential  number  indices  in  B2.  ) 

9  C’3  B  sortA  (  Sort  Bl  and  B2  with  respect  to  Bl .  ) 
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3  O 

C’3  A  exc 1 2 

(  Transfer  A2  to  A1 . 

) 

1  1 

C’3  A  sort A! 

(  Sor t  A 1 . 

) 

12 

C’3  A  exc 12 

(  Transfer  A1  to  A2. 

) 

13 

C’3  B  C’3  A  2  1  - : 

(  Transfer  indices  in  B2  to  Al. 

) 

14 

C ’ 3  A  sort A 

<  Sort  Al  and  A2  with  respect  to  indices 

) 

1  5 

C’3  A  exc 12  ; 

'  Transfer  snow  storm  from  A2  to  Al. 

) 

299 

LIST 

0 

(  Demonstrati  on  of 

Hi 

stoqram  Matching,  12  hrs.  Use  PRINT  DEMO 

) 

I 

: 

ADVANCE  0  DO  CR  LOOP  ; 

:  DFMO 

yt 

SMILEY-FACE 

( 

Generate  smiley  face  in  matrix  Al. 

) 

A 

OUTPIC 

( 

Print  smiley  face. 

} 

5 

37  ADVANCE 

( 

Advance  paper. 

) 

6 

C’3  A  C’3  B  1  1  - > 

< 

Transfer  smiley'  face  from  Al  to  Bl. 

) 

7 

C’3  A  r.ndfl 

f 

Fill  A 1  with  r an dom  n umb er s . 

) 

8 

31.5  T’3  A  at 

( 

Adjust  grey  level  values. 

) 

9 

OUTPIC 

( 

Print  random  image,  "snow  storm". 

) 

1  0 

17  ADVANCE 

< 

Advance  paper. 

) 

1  1 

C  ’  3  A  ex  c  1 2 

( 

Transfer  snow  storm  from  Al  to  A2. 

) 

12 

C ’ 3  B  C’3  A  1  1  -> 

( 

Transfer  smiley  face  from  Bl  to  Al . 

) 

13 

MATCH-Al-to— A2 

( 

Match  histogram. 

) 

1  4 
15 

OUTPIC  ; 

( 

Print  smiley  face  matched  to  snow  storm. 

) 

300 

LIST 

0  (  DEMO  uses  a  batch  least  squares  algorithm  to  -fit  a  10th 

1  (  order  polynomial  to  320  scattered  data  points  and  then 

2  (  display's  the  data  and  polynomial  graphically,  all  in 

3  (  5.628  seconds. 


5  320  12  matrix  XX  320  1  matrix  Y 

6  12  12  matrix  XTX  12  1  matrix  XTY  12  1  matrix  X  12  1  matrix  B 

7  :  FUNC  SIN  RND  . 5  F*  F+  .25  F-  ; 

8  *'•  :  DATA  320  0  DO  I  >N  50.77042685  F/  FDUP  1  0  XX  !  1  FUNC  FDUP 

9  I  0  Y  !1  75.0  F*  99.0  F+  N>  I  PLOT  LOOP  ; 

10  :  REG  C’3  XX  polyAl  C’3  XX  C’3  XX  C ’ 3  XTX  T*  C’3  XTX  INV 

11  C’3  XX  C’3  Y  C  ’  3  XTY  T*  C ’ 3  XTX  C4 5 6  7  3  XTY  C ’  3  B  A*  ; 

12  :  POLY  C’3  X  polyVl  C’3  X  C’3  B  0*  ; 

13  :  DRW  320  0  DO  I  >N  50.77042685  F/  POLY  75.0  F*  99.0  F+  N>  I 

14  PLOT  LOOP  ; 

15  :  DEMO  DARK  1  COLOR-SET  WHITE  DATA  REG  DRW  ; 


301  LIST 


0  (  Batch  least  squares  algorithm  is  used  to  find  12th 

1  (  order  polynomial  approximation  of  the  cosine  function 

2  (  between  -PI/2  and  PI/2.  Time  =  16.5  sec.  Error  =  2. IE-12 


4  1001  13  mat.*  ix  XX  1001  1  matrix  Y  variable  ERROR 

5  13  13  matrix  XTX  13  1  matrix  XTY  13  1  matrix  X  13  1  matrix 

6  :  REG  C’3  XX  polyAl  C’3  XX  r’3  XX  C’3  XTX  T*  C ’ J  XTX  INV 

7  C’3  XX  f’3  Y  C’3  XTY  T *  C’3  XTX  C’3  XTY  C’3  BA*  : 


B 


(Continued  on  next  page) 
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Fast  Matrix  Operations  (Listing  continued,  text  begins  on  page  44) 


8  :  POLY  CM  X  po!  ’>1  CM  X  CM  B  V*  ; 

9  :  BATA  1001  O  I  500  -  >N  .00105  F*  PI  F*  FDUP  I  O  XX  !  1 

10  COS  I  0  Y  !  1  L  OOP  ; 

11  i  FIND -COEFICIENTS  DATA  REG  CM  B  0  Cl.  ; 

12  :  MAX-ERROR?  0-0  ERROR  ! 1  1001  O  DO  I  500  -  >N  .001  Ft  PI  Ft 

13  FDUP  FSWAP  POLY  F-  FABS  FDUP  ERROR  35  F> 

14  IF  ERROR  '1  ELSE  FDROP  THEN  LOOP 

15  ERROR  31  CR  CR  . "  Maximum  Absolute  Error  =  "  N.  ; 


30?  LIST 


O  (  Sequential  Least  Squares  Applied  to  Time  Series  Analysis  ) 
1 

2  (  The  next  two  screens  contain  a  program  using  a  ) 

3  (  sequential  least  squares  algorithm.  To  demonstrate  ) 

4  (  use  n  DEMO  where  n  is  the  number  of  desired  iterations  } 

5  (  divided  by  1000  .  For  example,  1000  DEMO  will  iterate  ) 

6  (  one  million  times.  The  program  will  find  the  autoregressive) 

7  (  coeficients  stored  in  A  o.n  line  15  of  this  screen.  Here  A  ) 

8  (is  used  to  generate  ,  XL,  the  signal  that  is  being  analysed.) 

9  (  This  program  takers  22.7  seconds  per  1000  iterations.  ) 

1  0 

1 1 


1251  matrix  A  5  1  matrix  X  5  5  matrix  P  5  1  matrix  Xr  5  1  matrix 

13  PX  1  5  matrix  XTP  5  1  matrix  B  5  5  matrix  PXXTP  SVAR I ABLE  N 

14  SVAR I  ABLE  COUNT 

15  .60  0  A  ! 1  -.4  1  0  A  !1  -.2  2  0  A  !1  -.3  3  0  A  !1  -.1  4  0  A  !i 


303  LIST 

0  <  Sequential  Least  Squares,  Continued  ) 

1 

2  CODE  (shiftAl)  m  LDA  n  MUL  0  1  MOV  adr  LDA  65520  tt  W  MOV 

3  BEGIN  0  DS  LSG  R64  W  )  FLD  1  FXCH  R64  W  )  FSTP  0  INC  LOOP  0 

4  N)  FSTP  2  2  SUB  2  DS  LSG  NEXT  :  shiftAl  dim®  n!  m1  (shiftAl)  ; 

5  :  Xk  CM  X  CM  A  V*  RND  .5  F-  F+  FDUP  CM  X  shiftAl  ; 

6  :  Pr  CM  P  CM  Xr  CM  PX  At  CM  Xr  CM  P  CM  XTP  Tt  CM  PX  CM 

7  XTP  CM  PXXTP  At  CM  PX  CM  Xr  V*  1.0  F+  FNE6ATE  1 /N  CM  PXXTP 
a  at  CM  PXXTP  CM  P  A+  ; 

9  :  Ar  CM  P  CM  Xr  CM  PX  At  Xk  FDUP  CM  Xr  CM  B  Vt  F-  CM  PX 

10  a*  CM  PX  CM  E  A+  CM  Xr  shiftAl  ; 

11  £  DEMO  o'.  CM  B  clr  CM  Xr  cir  CM  P  12!  CM  P  e;;cl2  l.OE+15 

12  CM  F  at  0.0  COUNT  S!  10.0  N  S!  o®  0  DO  1000  0  DO  Pr  Ar  1.0 

13  COUNT  S3  F+  FDUP  COUNT  S!  N  S3  F=  IF  CF;  COUNT  S3  0  F.  .  "  Iterati 

14  ons  ’*  CM  BO  Cl.  N  S3  10.0  Ft  N  S!  CR  THEN  LOOP  LOOP  ; 

15 

End  Listing 
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And  Still  More 

Fifth  Generation  Computers! 


The  good  Doctor  enjoys  seeing  dialogue 
in  his  pages  on  timely  topics.  Richard  Gri- 
gonis  originally  submitted  a  guest  essay 
entitled  “Fifth  Generation  Computers’’ 
in  the  December  1982  issue  of  DDJ,  in 
which  he  briefly  presented  his  vision  of 
microcomputers  in  the  1990s.  Those 
predictions  were  challenged  in  the  March 
1983  issue.  In  response,  Mr.  Grigonis 
presents  here  a  more  detailed  treatment 
of  the  ideas  from  the  original  essay,  as 
well  as  some  further  predictions  and  his 
conceptualization  of  a  fifth-generation 
workstation.  -Ed. 

Open  Forum’s  “Comments  on  Fifth 
Generation  Computers,”  (March 
1983  DDJ,  No.  77)  by  Michael  J. 
Doherty,  contained  some  perceptive  in¬ 
sights  challenging  the  fifth-generation 
supermicro  that  I  proposed  in  “Fifth 
Generation  Computers”  (December  1982 
DDJ,  No.  74).  He  was  particularly  critical 
of  the  preciseness  of  my  predictions  re¬ 
garding  what  he  calls  the  “Grigonis  64/1 10 
processor,”  which  he  seems  to  think 
would  violate  the  known  laws  of  physics. 

This  article,  however,  shall  serve  to 
nullify  Mr.  Doherty’s  arguments  and  also 
to  satisfy  his  curiosity  to  see,  in  his  words, 
“Grigonis’  speculations  on  the  worksta¬ 
tion  environments  that  will  have  to  be 
developed  to  contain  the  operator  as  well 
as  the  advanced  hardware  he  describes.” 
Moreover,  in  this  article  I  will  do  both 
him  and  the  readers  of  DDJ  a  service  by 
precisely  predicting  the  development  of 
computers  (and  their  workstation  environ¬ 
ments)  over  the  next  50  years. 

First,  let  me  recount  the  features  of 
the  fifth -generation  supermicro,  expand¬ 
ing  my  explanations  as  we  go  along. 


64 -bit  processor  (von  Neumann  architec¬ 
ture)  running  at  1 10  MHz. 

Doherty  thought  that  putting  the 
equivalent  of  a  Cray  2S  on  a  chip  was  im¬ 
possible.  He  was  thinking  specifically  of 
certain  physical  boundary  conditions  im¬ 
posed  by  quantum  mechanics  —  namely, 
the  Planck  length  from  which  is  derived 
the  Heisenberg  Uncertainty  Principle,  in 


by  Richard  Grigonis 


Richard  Grigonis,  Children's  Television 
Workshop,  One  Lincoln  Plaza,  New  York, 
New  York  10023. 


this  case  applied  to  the  probable  locations 
of  the  electrons  in  the  signal  pathways  of 
the  processor  that  would  set  up  unusual 
field  effects  in  neighboring  signal  path¬ 
ways.  Doherty  also  thought  that  too 
many  gates  would  be  required  and  that 
the  switching  times  would  not  be  fast 
enough  to  handle  the  signal  densities 
required  for  a  supercomputer. 

I  am  sure  that  the  above  would  come 
as  a  surprise  to  the  scientists  at  the  Law¬ 
rence  Livermore  Laboratory  who  plan  to 
develop  the  Mark  V,  a  microprocessor 
four  times  as  fast  as  a  Cray! 

Let’s  also  take  a  look  at  the  Depart¬ 
ment  of  Defense  (DoD)  and  their  Very 
High-Speed  Integrated  Circuits  (VHS1C) 
Program.  Phase  la  of  this  program  is  to 
develop  chips  with  a  1.25  micrometer 
minimum  feature  size  and  an  equivalent 
gate-clock  frequency  product  exceeding 
5xl0n  gate-Hz/cm/  which  would  have  a 
maximum  power  dissipation  not  exceeding 
3  watts/cm?  The  minimum  clock  speed 
goal  is  25  MHz. 

Phase  lib  will  achieve  clock  rates 
above  30  MHz;  processor  signal  pathways 
will  have  submicrometer  feature  sizes  (0.5 
to  0.8  micrometer)  and  higher  gate  densi¬ 
ties;  and  the  gate-clock  frequency  product 
will  increase  to  about  1013gate-Hz/cm? 

The  manufacture  of  such  processors 
goes  beyond  present  IC  fabrication  tech¬ 
niques,  since  optical  lithography  is  bound 
by  a  one-micrometer  “barrier”  imposed 
by  the  highest  frequencies  of  visible  light, 
and  will  require  a  new  technology.  Phase 
III,  therefore,  will  examine  the  use  of 
“carving”  out  tiny  processor  signal  path¬ 
ways  and  electron  beams  (e-beams)  or 
using  lithographic  techniques  at  electro¬ 
magnetic  frequencies  higher  than  that  of 
visible  light  —  namely.  X-rays. 

Additional  speed  will  be  obtained 
simply  by  rethinking  the  whole  archi¬ 
tecture  of  processor  design  with  the  aid 
of  some  Computer  Aided  Design  (CAD) 
such  as  McWilliams’  Structured  Computer 
Aided  Logic  Design  (SCALD)  program, 
and  Artificial  Intelligence  programs.  We 
will  probably  end  up  with  optical  com¬ 
puter  chips  based  on  matrix-processing 
techniques  by  the  end  of  the  next  decade, 
quickly  supplanting  the  gallium  arsenide 
(GaAs)  chips  that  will  be  just  beginning 
to  flourish  in  the  early  1990s.  Besides, 
what’s  so  great  about  using  GaAs  as  an  IC 
substrate  anyway?  Its  much-touted  7-to- 
10-fold  speed  advantage  over  silicon  is 
dwarfed  by  silicon’s  100-fold  gate  density 
advantage. 


Interestingly,  the  speed  of  light  dic¬ 
tates  that  all  of  the  most  advanced  main¬ 
frames  appearing  at  the  end  of  the  next 
decade  will  in  fact  be  either  micros  or  at 
least  the  size  of  micros.  If  the  travel  time 
of  the  signals  between  switches  does  not 
exceed  the  switching  time,  then  the  dis¬ 
tance  between  the  farthest  two  switches, 
or  the  length  of  the  longest  signal  path¬ 
way,  must  always  be  less  than  or  equal  to 
the  switching  time  multiplied  by  the 
speed  of  light.  As  Seymour  Cray  learned, 
if  the  switching  time  is  one  nanosecond 
(10"9  sec),  then  the  length  of  any  signal 
pathway  in  the  processor  must  not  exceed 
30  centimeters.  Mainframe  processors  at 
the  beginning  of  the  next  decade  will 
have  switching  times  of  about  1CT10  of  a 
second,  so  their  signal  pathways  cannot 
exceed  3  centimeters.  Computers  around 
the  year  2010  will  have  switching  times  of 
about  6  picoseconds  (6  x  10'12  sec),  re¬ 
stricting  signal  pathway  lengths  to  a  little 
over  0.15  centimeters!  Quite  a  big  “main¬ 
frame,”  eh? 

Josephson  circuits  can  already  be 
switched  in  13  picoseconds,  7  picoseconds 
for  the  actual  switching  time  and  6  pico¬ 
seconds  for  the  signal  to  traverse  the 
circuits.  This  is  approaching  as  fast  a 
switching  time  as  is  theoretically  allowed. 
4nd  since  the  signals  travel  at  nearly  the 
speed  of  light  in  the  Josephson  circuit 
substrate  material  (0.003  inch  per  pico¬ 
second  —  and  that’s  with  a  minimum  line 
width  as  large  as  2.5  microns),  the  prob¬ 
lem  now  is  not  to  make  the  switches 
faster,  but  to  place  them  closer  together. 

Actually,  Doherty  is  sort  of  right,  but 
the  Uncertainty  Principle  enters  into  the 
discussion  in  a  different  way.  The  funda¬ 
mental  limit  of  all  computation,  even  that 
of  the  human  brain,  is  mathematically 
identical  with  the  Uncertainty  Principle 
of  quantum  mechanics.  By  this,  I  mean 
that  the  acts  of  signals  triggering  switches 
are  physical  measurements,  and  the  accu¬ 
racy  of  all  physical  measurements  is  sub¬ 
ject  to  the  Uncertainty  Principle.  The 
faster  the  measurements,  the  more 
unreliable  they  will  be,  resulting  in  a 
downward  spiral  of  more  and  more  error- 
correcting  circuitry. 

We  can  reduce  error  by  increasing  the 
signal  energy,  but  we  cannot  continue 
doing  this  indefinitely,  as  the  processor 
will  melt!  According  to  physicist  Hans  J. 
Bremermann,  the  “trade-off”  between 
the  number  of  distinguishable  signals 
(information)  that  can  be  sent  is  propor¬ 
tional  to  the  time  required  to  identify 
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them:  E/h[sec_1  ] ,  where  E  is  the  energy 
available  for  signalling,  and  h  is  Planck’s 
constant.  This  limit  applies  to  the  human 
brain  as  well  as  computers. 

Another  physical  limit,  also  dis¬ 
covered  by  Bremermann  in  1961,  takes 
into  account  the  fact  that  the  energy  of 
the  signals  has  a  “mass”  just  like  matter: 
no  computer  can  have  a  signal  flow  ex¬ 
ceeding  mc2/h  bits  per  second,  where  m 
represents  the  total  mass  of  the  system, 
c  is  the  velocity  of  light,  and  h  is  Planck’s 
constant.  Theoretically,  the  maximum 
signal  flow  for  any  calculating  device  or 
even  any  physical  implementation  oi  any 
algorithm  is  1.35  x  1041  bits  per  second 
per  gram  of  system  weight.  Since  today’s 
supercomputers  run  at  about  10s  bits  per 
second  per  gram,  we  have  a  long  ways  to 
go  before  hitting  the  maximum. 

Yet  a  third  limit  is  not  a  physical 
Emit,  but  a  limit  of  algorithm  complexity. 
This  is  not  quite  as  bad  as  the  other  two 
limits  since  we  can  always  find  shortcuts 
to  mathematical  problems  once  considered 
hopeless,  or  “transcomputable.”  A  per¬ 
fect  example  of  this  is  the  travelling  sales¬ 
man  problem.  A  salesman  must  find  the 
shortest  path  between,  say,  10  cities. 
The  trial-and-error  computational  cost  of 
doing  this  is  181,440  steps.  One  can  see 
that  this  problem  is  important  to  hard¬ 
ware  designers  as  they  are  always  figuring 
out  ways  of  cramming  the  most  circuits 
in  the  least  volume  by  finding  the  shortest 
signal  path  between  switches.  The  difficul¬ 
ty  comes  when  we  increase  the  number  of 
cities  or  switches  to  100,  which  requires 
10100  steps.  Calculating  the  distance  be¬ 
tween  400  cities  would  require  lO800 steps. 
This  figure  vastly  exceeds  the  10120  total 
possible  moves  in  chess! 

But  now  three  IBM  researchers  have 
discovered  that  some  equations  from  sta¬ 
tistical  mechanics  provide  an  amazing 
shortcut  to  the  problem.  If  we  pretend 
that  the  circuits  are  water  molecules,  then 
the  shortest  length  through  all  of  them 
can  be  found  if  we  “cool”  them,  bringing 
them  closer  together.  The  minimum  dis¬ 
tance  between  400  circuits  can  now  be 
calculated  with  just  a  million  ( 1 06)  steps! 

I  think  Mr.  Doherty,  therefore, 
should  not  worry  about  “theoretical 
limits.” 

An  actor -based  program  and  language 
generator.  A  sort  of  Smalltalk  version  of 
The  Last  One  which  develops  the  opti¬ 
mum  language  for  execution  as  well  as 
the  code  defining  the  flow -of- control. 

Now  that  we  are  on  the  subject  of 
languages,  1  must  mention  the  Japanese 
Fifth  Generation  project,  which  started 
this  whole  debate.  Let  me  state  that  al¬ 
though  the  Japanese  will  undoubtedly 
develop  the  tremendously  advanced  hard¬ 
ware  they  have  set  as  a  goal  for  them¬ 
selves  —  a  computer  100  times  faster  than 
a  Cray  1  —  the  fatal  flaw  in  the  project  is 
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the  software,  particularly  the  use  of  the 
language  Prolog  in  their  Artificial  Intel¬ 
ligence  programs. 

The  first  problem  with  the  Japanese 
is  that  they  have  decided  to  take  a  crea¬ 
tive  lead  in  the  area  of  supercomputer 
hardware  and  software.  Under  no  circum¬ 
stances,  therefore,  are  they  going  to  imi¬ 
tate  what  the  Americans  have  been  doing 
with  Artificial  Intelligence.  The  initial 
result  of  this  policy  was  their  decision 
not  to  use  LISP,  the  lingua  franca  of 
American  A I  research. 

I  have  a  few  bones  to  pick  with  LISP 
myself:  the  parentheses  notation,  the  fact 
that  it  is  slow  (except  for  the  optimized 
MACLISP  math  functions)  both  because 
the  language  is  interpreted  and  because 
the  processor  must  chase  thousands  of 
pointers  around,  the  unsophisticated  dy¬ 
namic  scoping,  the  method  of  garbage  col¬ 
lection,  its  near  non-transportability  (as 
opposed  to  Ada  or  “C”),  and  the  ominous 
fact  that  although  it  is  the  second  oldest 
computer  language  (McCarthy  started 
working  on  it  in  1958,  a  year  after  the 
first  Fortran  compiler  appeared)  it  has 
never  been  used  for  anything  outside  the 
field  of  Artificial  Intelligence! 

Still,  LISP  can  treat  its  own  programs 
as  data,  can  modify  itself  or  write  new 
programs  and  evaluate  them.  The  language 
is  extensible,  and  the  eight  or  so  basic, 
primitive  functions  constitute  a  universal 
Turing  machine  and  can  be  used  to  calcu¬ 
late  anything  that  can  be  calculated.  LISP 
has  been  around  so  long  that  there  exist 
sophisticated  software/hardware  develop¬ 
ment  tools  for  it  such  as  the  Xerox  and 
Symbolics  3600  “LISP  Machines.” 

So  what  have  the  Japanese  selected 
instead?  Prolog,  an  obscure  language 
developed  by  the  French  and  “polished” 
a  bit  by  the  British.  Prolog  is  the  funda¬ 
mental  error  in  the  otherwise  sound 
Japanese  Fifth  Generation  project. 

This  brings  us  to  the  second  problem 
with  the  Japanese,  which  is  their  quest 
for  absolute  perfection.  This  seems  to  be 
an  outgrowth  of  Japanese  philosophy  in 
general,  and  had  until  recently  motivated 
them  technologically  to  make  fools  out 
of  their  American  competition.  One  of 
the  reasons  they  chose  the  obscure  Prolog 
language  was  their  problems  with  under¬ 
standing  traditional  Western  programming 
languages.  The  Japanese  and  Chinese  use 
ideographic,  “picture”  languages  to  com¬ 
municate  with  each  other  instead  of  the 
linear,  lexical,  “letter-and-word”  lan¬ 
guages  of  the  Europeans.  The  Japanese 
thus  tend  to  think  in  terms  of  patterned 
wholes,  whereas  Westerners  think  along 
linear,  reductionist  sequences.  This  leads 
to  interesting  effects:  Someone  in  Japan 
can  look  at  the  pictograms  in  a  Chinese 
newspaper  and  understand  the  meaning 
of  the  words  and  the  sentences  without 
having  the  slightest  idea  of  their  pronun¬ 
ciation,  while  an  American  can  look  at  an 


Italian  newspapers  pronounce  the  words 
correctly,  even  identify  the  nouns  and 
verbs  correctly,  but  cannot  understand  a 
thing! 

The  one  area  where  the  Japanese 
computer  scientists  are  on  an  equal  foot¬ 
ing  with  their  American  counterparts  is 
in  a  different  linguistic  realm  entirely  - 
namely,  the  notations  of  pure  symbolic 
logic,  as  developed  by  Boole  and  Frege. 
What  attracted  them  to  Prolog  is  that  its 
“horn- clause”  notation  and  axiom- 
theorem  structure  force  the  programmer 
to  use  the  first-order  predicate  calculus. 
Thus,  instead  of  millions  of  arithmetic 
calculations  per  second,  the  Japanese  will 
measure  the  power  of  their  computer  in 
terms  of  the  number  of  what  they  call 
“LIPS”  or  Logical  Instructions  Per  Sec¬ 
ond.  Now,  although  representing  knowl¬ 
edge  procedurally  via  heuristics  in  LISP  is 
a  standard  way  of  doing  things  in  Ameri¬ 
can  AI  programs,  the  only  declarativist 
means  of  representing  knowledge  that 
ideally  surpasses  procedural  representa¬ 
tions  is  logic.  Hence,  Prolog  became  the 
language  of  choice  for  the  Japanese. 

I  mentioned  above  that  logic  is  ideally 
a  perfect  way  of  representing  knowledge 
—  but  the  qualifying  word  is  “ideally.”  In 
reality,  logical  knowledge  representation 
and  inference  calculation  is  a  nightmare 
for  a  computer.  The  addition  of  just  a  few 
hundred  facts  to  the  “knowledge  base” 
forces  the  computer  to  calculate  all  of  the 
possible  logical  relationships  (inferences) 
between  all  of  the  other  facts  currently 
stored  in  the  system  and  the  new  facts 
themselves,  resulting  in  a  “combinatorics 
explosion”  that  fills  up  both  the  internal 
memory  and  the  disk  storage.  Even  a 
slight  change  or  revision  of  a  few  crucial 
facts  can  cause  an  avalanche  of  updating. 

Various  ways  have  been  tried  to  get 
around  this  problem.  Some  Stanford 
researchers  are  attempting  to  add  only 
temporary  “local”  changes  to  the  knowl¬ 
edge  base,  recalculating  all  of  the  logical 
relationship  changes  only  periodically. 
Apparently,  the  Japanese  plan  to  conquer 
the  problem  with  brute  force,  building 
computers  with  huge  amounts  of  internal 
memory,  disk  storage,  and  a  processor 
that  may  achieve  billions  of  logical  opera¬ 
tions  in  a  second. 

But  before  their  grand  supercomput¬ 
er  is  ready,  the  Japanese  are  planning  to 
market  (sometime  in  1984)  smaller,  per¬ 
sonal  computer  versions  of  their  system, 
called  “Prolog  machines.”  The  Japanese 
seem  aware  of  the  problems  they  have 
created  for  themselves  and  are  not  entirely 
excluding  the  possibility  of  using  LISP 
functions.  Indeed,  one  of  the  companies 
participating  in  the  project  has  a  goal  of 
producing  the  world’s  fastest  LISP  ma¬ 
chines  as  well.  The  Japanese  insist  that 
they  are  “spelling  prolog  with  a  small  p,” 
meaning  that  they  may  not  be  using  just 
the  strict  logical  structure  of  Prolog  (with 
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a  capital  P)  as  originally  developed  by  the 
Europeans. 

4-megabyte  EEPROM  memory  chips, 
with  a  total  of  32  megabytes  of  memory. 

10,000-to- 15,000 -megabyte  optical  disc 
drives.  (The  industry,  when  describing 
optical  storage,  spells  disk  with  a  “c”; 
when  referring  to  magnetic  storage,  disk 
is  spelled  with  a  “k.  ”) 

Flat  screens  displaying  three  WP  pages,  or 
three  sections  of  a  DP  program  simulta¬ 
neously,  in  color. 

Rather  than  a  single  wide  screen,  in 
the  manner  of  the  inexpensive,  portable¬ 
looking  model  that  artist,  A1  McCahon, 
drew  to  illustrate  the  cover  of  the  Decem¬ 
ber  1983  DDJ  issue,  the  office  version 
will  actually  be  constructed  so  that  the 
three  main  screens  are  arranged  in  a  trip¬ 
tych,  reminiscent  of  the  arrangement  of 
screens  employed  in  the  recent  release  of 
the  movie  Napolean.  In  this  way,  both  the 
optical  and  geometric  centers  of  the  screen 
are  kept  equidistant  from  the  eyes  of  the 
viewer,  so  the  user  can  look  at  any  screen 
in  succession  without  eyestrain. 

Also,  beneath  the  corners  of  both  the 
left  and  right  screens  will  be  located  two 
additional,  smaller  screens.  One  screen 
will  display  the  page  appearing  prior  to 
the  one  currently  displayed  on  the  larger 
screen  above,  the  other  one  displaying  the 
page  after  it.  While  working  on  one  of  the 
peripheral  larger  screens  then,  the  user 
need  only  glance  down  to  look  at  preced¬ 
ing  or  succeeding  pages,  if  any,  instead  of 
swinging  one’s  head  150  degrees  to  the 
farthest  of  the  larger  screens.  In  this  way 
the  user  can  command  the  three  large 
screens  to  hold  three  pages  from  totally 
different  sections  of  a  file  undergoing 
editing  without  the  fear  of  losing  one’s 
perspective  of  the  continuity  of  the  file. 
The  central  screen  does  not  have  subsidi¬ 
ary  screens,  partly  because  of  the  space 
taken  up  by  the  keyboard  and  partly 
because  users  will  probably  use  the  cen¬ 
tral  screen  as  a  sketchpad,  or  a  temporary 
work  area  (such  as  the  disembodied 
“work  page”  as  can  be  currently  found  in 
the  WP  documents  on  Wang  equipment) 
where  material  from  various  areas  is 
stored  and  polished  before  it  is  reinserted 
in  the  file  proper. 

A  mouse  replacing  the  cursor  directional 
keys.  This  prediction  came  true  a  lot 
sooner  than  1992  ( it  was  the  month  after 
the  appearance  of  my  article,  in  fact), 
when  the  one- button  mouse  was  an¬ 
nounced  as  standard  equipment  on  the 
new  Apple  Lisa. 

By  the  turn  of  the  century,  however, 
the  mouse  will  have  a  successor  —  two 
successors,  actually.  One  is  an  attachment 


either  built  into  the  headrest  of  the  user’s 
chair  or  else  set  on  each  of  the  three 
screens,  consisting  of  a  low-power  semi¬ 
conductor  laser  projecting  and  scanning 
an  invisible  light  beam  (in  a  harmless  end 
of  the  spectrum)  onto  the  user’s  eyes.  A 
flat  semiconductor  “lensless”  camera  will 
read  the  light  of  the  reflected  beam  and 
track  the  movements  of  the  user’s  eyes 
across  the  screen.  If  the  user  wishes  to 
make  a  specific  selection  on  a  menu,  one 
will  focus  one’s  gaze  on  the  appropriate 
icon  and  press  a  foot  pedal,  telling  the 
computer  that  the  current  line  of  sight  is 
to  be  construed  as  a  menu  selection  or 
perhaps  an  INPUT  command  if  the  action 
occurs  during  a  program  run. 

The  above  is  fine  for  repositioning 
the  cursor  quickly  within  the  boundaries 
of  the  screen.  But  what  about  scrolling 
the  screen  “windows”  through  a  file? 
This  is  where  the  second  device  comes  in 
—  a  box  attachment  to  the  armrest  upon 
which  is  mounted  an  arcade-style  “track¬ 
ball”  and  some  buttons.  In  the  WP  editor, 
spinning  the  ball  to  the  right,  for  example, 
will  “flip”  pages  from  the  small  right- 
hand  corner  screens  (succeeding  pages)  to 
the  larger  screens,  and  then  back  again  to 
the  smaller,  left-hand  screens  (preceding 
pages),  until  the  end  of  the  document  is 
reached.  It  should  be  amusing  to  set  up 
all  the  screens  so  that  they  are  looking  at 
one  segment  of  seven  continuous  pages 
and  then  spinning  the  ball  and  watching  a 
train  of  pages  appear  in  succession  on  all 
of  the  screens  (sort  of  like  doing  word 
processing  in  Cinerama!).  When  the  user 
is  working  on  a  DP  spread-sheet,  the 
trackball  can  be  used  to  scroll  either  side¬ 
ways  across  the  matrix,  up-and-down, 
or  even  on  a  diagonal. 

When  the  screen  stabilizes,  the  eye 
scanner  cursor  controls  will  again  become 
functional.  If  the  user  is  not  looking  at  an 
icon,  but  at  a  line  from  a  WP  or  DP  file 
when  he  or  she  presses  the  pedal,  then  the 
computer  considers  this  action  to  be  an 
EXECUTE  command  in  the  DP/WP 
editor.  In  this  way,  editing  would  still 
consist  of  the  user  pressing  INSERT, 
DELETE,  REPLACE,  or  MOVE  keys, 
but  doing  so  would  cause  the  laser  scan¬ 
ning  device  to  activate  the  chosen  editing 
command  at  the  cursor  position  set  by 
the  user’s  line-of-sight. 

A  description  of  a  MOVE  editing 
operation  in  a  futuristic  operating  manual 
of  the  middle  of  the  next  decade  may 
read  something  like  this: 

(1)  Deactivate  the  screen  cursor  by 
looking  at  the  beginning  of  the  block  of 
characters  to  be  moved  and  pressing  the 
MOVE  button.  The  first  character  of  the 
block  that  you  are  looking  at  should  now 
be  highlighted.  Do  not  press  any  alpha¬ 
numeric  character  keys  at  this  point,  as  it 

will  cancel  the  operation  and  the  normal 
screen  cursor  will  reappear,  but  this  time 


at  the  screen  location  at  which  you  were 
just  looking. 

(2)  Continue  highlighting  the  block 
to  be  moved  by  reading  the  text  until  you 
reach  the  end  of  the  block  or  by  just 
glancing  down  at  a  specific  character 
(period,  paragraph  return  character,  etc.). 
Remember,  the  text  will  be  highlighted 
from  the  initial  point  at  which  you  pressed 
the  button  to  the  point  you  are  currently 
looking  at.  Looking  to  the  left  or  up  on 
the  screen  will  dehighlight  the  formerly 
highlighted  areas. 

(3)  When  you  are  satisfied  with  the 
size  of  the  highlighted  block  to  be  moved, 
keep  staring  at  the  last  character  of  the 
block  and  step  on  the  ENTER/EXECUTE 
pedal.  The  highlighted  area  will  disappear 
off  of  the  screen. 

(4)  Reposition  your  gaze  at  the  new 
location  where  the  block  is  to  be  inserted. 
If  you  must  give  commands  to  go  to  a 
totally  different  file,  then  the  system  will 
ignore  your  line-of-sight  gaze  until  it  is 
again  within  the  stabilized  screen  area. 
Look  at  the  screen  location  where  the 
block  is  to  be  inserted. 

(5)  Step  on  the  ENTER/EXECUTE 
pedal.  The  block  of  characters  should 
now  have  been  inserted  starting  at  the  last 
screen  location  you  were  looking  at  when 
you  pressed  the  pedal.  Notice  that  the 
cursor  has  now  reappeared,  also  in  this 
same  location  at  the  beginning  of  the 
moved  block. 

There  may  be  a  few  other  features,  such 
as  a  fully  programmable  keyboard  that 
allows  the  user  to  reconfigure  the  keys  to 
the  Dvorak  “speedboard  ”  arrangement. 

The  Workstation 

The  main  emphasis  in  the  design  of 
the  workstation  —  and  the  general  working 
environments  -  of  the  1990s  and  beyond 
will  be  a  total  dedication  to  efficiency 
and  productivity,  regardless  of  initial 
start-up  costs  or  peculiar  design  features. 
We  will  have  come  far  from  the  days  of 
World  War  II,  when  defense  contractors 
discovered  that  productivity  could  be  im¬ 
proved  by  putting  back  supports  on  the 
stools  used  by  assembly  line  workers! 

The  offices  of  the  future  will  be  highly 
security -oriented.  There  will  be  no  harsh 
lighting,  and  the  rooms  containing  the 
supermicros  and  their  workstations  will 
be  set  in  a  dust-free  environment  —  no 
dust,  dirt,  pollen,  extraneous  carbon  mon¬ 
oxide,  or  sufur  dioxide  from  the  exterior 
urban  environment  will  be  allowed  into 
the  office.  Negative  ions  and  additional 
oxygen  will  be  pun-  ,ed  into  the  air.  Many 
employees  will  oe  working  at  home, 
however,  via  telecommuting. 

The  office  visitor  will  first  notice  the 
workstations:  a  number  of  large,  off- 
white  plastic  arches,  looking  a  little  like 
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miniature  quonset  huts,  each  sitting  atop 
a  short  pedestal.  A  series  of  two  or  three 
steps  leads  up  the  side  of  each  pedestal 
to  the  arch.  These  workstations  are  scat¬ 
tered  around  the  room,  with  large  num¬ 
bers  affixed  to  the  back  of  them. 

Looking  inside  one  of  the  worksta¬ 
tions,  one  sees  our  old  friend  the  super¬ 
micro,  the  keyboard/screens/chair  frame¬ 
work  set  within  the  arch.  Modular  con¬ 
stitution  seems  evident  and  whole  sections 
(keyboard,  screens)  can  be  replaced  easily. 
The  user  climbs  into  the  chair  and  lowers 
what  appears  to  be  two  large  additional 
armrests  that  pivot  down  on  either 
side,  each  actually  a  sort  of  counter, 
which  corral  the  user  in  the  workstation. 
Florescent-type  bulbs  built  into  the 
counter  backboards  illuminate  any  odds 
and  ends  the  user  wishes  to  place  on  the 
counters  to  refer  to  in  the  course  of  a 
session  with  the  computer.  One  notices 
that  all  the  interior  plastic  is  of  a  soft, 
non-glare,  earth  color  variety. 

The  pressure  of  sitting  in  the  chair 
automatically  activates  the  low-intensity 
flat  screens.  Normal  room  light  would 
wash  them  out,  which  is  another  reason 
for  the  totally  enclosed  workstation.  An¬ 
other  reason  is  that  the  user  has  privacy 
and  has  the  option  of  turning  on  stereo 
loudspeakers  built  into  the  chair  headrest 
that  can  play  music,  “white  noise,” 
nature  sounds,  etc. 

The  user  sees  some  drawers  set  be¬ 
neath  the  keyboard.  Instead  of  keys, 
authorized  personnel  are  able  to  open 
drawers  (and  similarly  gain  access  to  cer¬ 
tain  files  and  functions)  through  voice 
recognition.  The  user  will  probably  sit  in 
the  chair  and  deliver  a  rambling  mono¬ 
logue  into  a  microphone  built  into  the 
workstation  until  the  computer  signals 
that  it  has  identified  the  user  and  has 
given  him  or  her  the  authority  to  use  the 
designated  functions  and  files. 

The  chair/screen/keyboard  motor 
controls  can  be  found  on  the  chair  arm¬ 
rests.  The  user  moves  the  chair  a  bit 
closer  to  the  screen  and  then,  deciding  to 
work  in  a  more  supine  position,  presses 
another  button  and  rotates  the  framework 
backwards.  As  the  chair  leans  back,  the 
keyboard  moves  up  and  stays  in  the  same 
relative  position  the  user  had  set  it  in 
earlier,  as  do  the  screens,  following  tracks 
built  into  the  underside  of  the  arch. 

After  selecting  some  “environmental 
sounds”  to  play  through  the  headrest 
speakers,  adjusting  the  temperature  of  the 
chair,  and  setting  the  negative  ion  level  in 
the  workstation  atmosphere,  the  user  is 
off  and  running .... 

2000  and  Beyond 

Since  DDJ  is  essentially  a  systems  soft¬ 
ware  journal,  I  will  only  briefly  describe 
sociological  developments  occurring  as  a 
consequence  of  this  kind  of  equipment 


beyond  the  year  2000.  Besides,  it  is  best 
that  the  public  not  know  that  they,  within 
50  years,  are  all  going  to  resemble  hackers 
to  one  degree  or  another.  In  any  event,  I 
predict  the  following: 

Mass  transit  is  a  mass  waste  of  time, 
so  telecommuting  will  flourish.  There  will 
still  be  work  centers,  but  part  of  one’s 
salary  will  no  longer  be  devoted  to  trans¬ 
porting  oneself  to  the  office. 

For  nationwide  teleshopping,  the  user 
at  home  receives  a  holographic  plate  in 
the  mail  upon  which  is  stored  the  con¬ 
tents  of,  say,  a  Sears  catalogue.  Many 
separate  holographic  images  can  be  stored 
on  one  photographic  plate  simply  by 
changing  the  angle  of  the  reference  beam 
between  exposures.  The  user  puts  the 
plate  in  a  viewing  device  and  spins  it  to 
change  the  direction  of  the  illuminating 
beam  and  observe  the  different  products. 
Selecting  one,  the  user  calls  up  his  video¬ 
tex  system  and  finds  out  which  “point  of 
distribution”  (a  cross  between  a  store  and 
a  warehouse)  has  the  best  price.  After  sig¬ 
nalling,  the  transaction  is  recorded  and  an 
extensive  delivery  system  goes  into  action, 
bringing  the  product  to  the  user’s  home. 

The  streamlining  of  oral  and  written 
language,  with  so  many  people  using  com¬ 
puters,  means  the  written  language  will 
take  on  a  more  ideographic  quality.  We 
will  see  the  appearance  of  “videoglyphs” 
(as  some  researchers  call  them),  which  are 
ways  of  throwing  entire  concepts  and  huge 
blocks  of  information  on  a  screen  very 
quickly  in  pictographic  form.  This  will 
damage  the  appreciation  of  our  slower, 
more  flowery  written  language  even  more 
than  did  television.  Our  written  and  oral 
language  will  seem  cumbersome. 

Since  computers  will  give  their  users 
nearly  instantaneous  responses,  people 
will  communicate  with  the  equipment  at 
their  own  pace.  After  years  of  doing  this 
for  each  working  day  (or  school  day,  in 
the  case  of  children),  catastrophic  effects 
on  interpersonal  communication  will  re¬ 
sult.  People  will  suddenly  lose  the  ability 
to  tolerate  others  not  spewing  out  or 
receiving  information  as  fast  as  they  do 
in  a  conversation.  I  see  this  phenomenon 
appearing  among  hackers  right  now.  The 
solution  to  this  interpersonal  communica¬ 
tions  problem  seems  to  be  the  one  the 
hackers  have  already,  albeit  unconsciously 
devised:  Although  two  of  them  are  sitting 
at  terminals  near  each  other,  they  commu¬ 
nicate  via  the  computer  with  themselves 
and  as  many  others  in  their  telecommuni¬ 
cations  network  as  they  can  comfortably 
accommodate.  We  will  live  in  a  world 
where  everyone  will  be  an  acquaintance 
of  everyone  else,  but  few  personal  friend¬ 
ships  will  exist. 

Also,  since  all  of  the  world’s  informa¬ 
tion  will  eventually  be  in  the  form  of 
huge  databases,  advanced  information 
retrieval  techniques  of  document  titles 


alone  (like  those  employed  by  the  Lock¬ 
heed  Dialog  system)  will  prove  to  be  in¬ 
sufficient  and  will  overwhelm  the  user. 
Thus,  an  Artificial  Intelligence  program  - 
a  natural  language  processing  front  end, 
to  be  specific  —  will  have  to  be  placed 
between  the  user  and  the  enormous 
databases. 

The  users  will  now  be  able  to  access 
any  information  they  please  at  the  push 
of  a  button.  Society  will  reason  that  a 
generalized  liberal  arts  education  is  too 
expensive  and,  in  any  case,  is  no  longer 
necessary  since  the  information  is  always 
there  if  one  has  to  look  it  up.  The  prob¬ 
lem  is  —  nobody  will  look  it  up.  The  edu¬ 
cational  curriculum  will  become  highly 
specialized.  This,  plus  the  long-term 
exposure  to  supercomputer  AI  program¬ 
ming,  will  transform  the  users  into  what 
might  best  be  described  as  idiot  savants, 
or  hackers  without  the  technical  expertise. 

Entertainment  will  be  provided  by 
huge  arcades  where  three-dimensional 
“entertainment  experiences”  will  occur. 
These  experiences  will  be  far  more  “inten¬ 
sive”  than  what  can  be  conceived  of  at 
present  since  people  become  bored  very 
easily  with  any  particular  level  of  sight - 
and-sound  effects  technology  and  crave 
something  new.  One  realizes  how  trite 
Space  Invaders-type  games  appear  to  us 
now,  as  opposed  to  how  exciting  they 
seemed  just  a  few  years  ago. 

Schools  will  be  replaced  with  “educa¬ 
tional  interaction  centers.”  The  less  said 
about  them  the  better.  After  all,  imagine 
your  child  sitting  in  a  dark  room  at  a  long 
row  of  keyboards,  being  “programmed” 
by  society  to  become  an  extension  of  the 
equipment,  not  vice  versa. 

Get  the  picture? 
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RED 

A  Better  C  Screen  Editor,  Part  II 


Last  month  I  introduced  RED,  a  new 
screen  editor  which  is  written  in 
Small-C.  That  article  covered  RED’s 
buffering  scheme  in  great  detail.  This 
month  I’ll  discuss  the  Small-C  Library 
used  in  RED  and  improvements  that 
might  be  made  to  RED.  I’ll  also  say  a  few 
words  about  why  RED  is  copyrighted. 

To  the  user,  RED  appears  very  simi¬ 
lar  to  the  ED2  editor  described  in  the 
January  1982  issue  of  Dr.  Dobb’s  Journal. 
Because  of  this,  the  remainder  of  RED  is 
provided  in  Listing  One  (page  66)  without 
extensive  discussion.  Tables  1,  2  (at  right), 
and  3  (page  64)  give  a  brief  summary  of 
RED  for  those  not  familiar  with  the  origi¬ 
nal  editor. 

A  New  Run-Time  Library 
for  Small-C 

The  buffer  routines  described  last 
month  require  a  run-time  library  which 
supports  “unbuffered,”  i.e.,  block -at-a- 
time,  file  access.  The  new  library  presented 
in  Listing  Two  (page  87)  is  an  edited  and 
slightly  modified  version  of  part  of  the 
BDS  C  run-time  library.  (There  is  a  lot 
more  to  the  library  that  I  have  not  in¬ 
cluded.)  This  library  is  presented  here  by 
permission  of  its  author,  Leor  Zolman. 

I  have  tried  to  make  sure  that  the 
routines  presented  here  work  exactly  the 
same  as  the  original  BDS  C  library  rou¬ 
tines.  Changes  to  the  code  were  made 
only  where  absolutely  necessary  and  are 
marked  in  the  listing.  The  changes  were 
made  because  Small-C  pushes  arguments 
on  the  stack  in  reverse  of  the  order  that 
BDS  C  uses.  Small-C  pushes  parameters 
in  the  order  in  which  they  appear  in  the 
parameter  list.  Thus,  the  last  argument  in 
the  list  appears  at  the  top  of  the  stack 
(right  under  the  return  address).  In  BDS 
C,  the  first  argument  appears  at  the  top 
of  the  stack. 

The  new  library  passes  command  line 
arguments  to  the  main()  function.  To  re¬ 
trieve  these  arguments,  add  two  arguments 
to  main()  as  follows: 
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Table  1 

COMMAND  MODE 

append  file  . Append  file  after  the  current  line. 

change  line  range . Change  lines  which  match  a  pattern. 


?  in  search  mask  matches  any  character. 

?  in  change  mask  becomes  character  that  matched  corresponding 
?  in  the  search  mask. 

A  in  search  mask  in  column  1  matches  the  start  of  a  line. 


clear . Clear  the  buffer. 

copy  line  range  number  .  .Copy  lines  in  line  range  after  line  number. 

delete  line  range . Delete  ALL  lines  in  line  range. 

dos  . Exit  from  RED. 

find . Go  to  next  line  that  matches  a  pattern. 

?  and  A  as  in  change  command. 

g  number  . Go  to  line  number. 

help . Print  a  help  message  for  command  mode. 

list  line  range . List  lines  to  the  printer. 

load  file  . Load  the  buffer  from  a  file. 

move  line  range  number  .  .Move  lines  in  line  range  after  line  number. 

name  filename . Make  filename  the  current  file  name. 

resave . Save  the  buffer  to  an  existing  file. 

save . Save  the  buffer  to  a  new  file. 

search  line  range . Search  for  a  pattern. 

?  and  A  as  in  change  command, 

tabs  number  . Set  tab  stops  to  every  number  column. 


Table  2 

SPECIAL 

CHARACTERS 

Key 

Default  Value 

Result 

up  key: 

control  -u  .  . 

Move  the  cursor  up.  Enter  edit  mode. 

down  key: 

control -d  .  . 

Move  the  cursor  down.  Enter  edit  mode. 

right  key: 

control  -r .  .  . 

Move  the  cursor  right. 

left  key: 

back  space  .  . 

Move  the  cursor  left. 

insert  up  key: 

LF . 

Insert  a  new  line  above  the  current  line. 

Enter  insert  mode. 

insert  down  key: 

CR . 

Insert  a  new  line  below  the  current  line. 

Enter  insert  mode. 

delete  character  key : 

DEL . 

Delete  one  character. 

delete  line  key: 

control  -z  .  . 

Delete  the  current  line. 

insert  key: 

control  -n  .  . 

Enter  insert  mode. 

command  key: 

escape  .  .  .  . 

Enter  command  mode. 

edit  key: 

control  -e  .  . 

Enter  edit  mode. 

undo  key: 

control -x  .  . 

Undo  changes  to  the  current  line. 

split  key: 

control -s  .  .  . 

Split  the  current  line. 

join  key: 

control -p  .  . 

Join  current  line,  preceding  line. 

repeat  key: 

conrol-a  .  .  . 

Repeat  the  previous  character. 
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main(argc,  argv) 
int  argc ; 
int  *  argv; 

/*  Kludge:  should  be  char  **  argv  */ 

Argc  is  one  more  than  the  number  of 
arguments  on  the  command  line.  Argv  is  a 
pointer  to  an  array  of  pointers  to  the  actu¬ 
al  arguments.  Argv  [0]  is  not  used,  thus 
argv  [  1  ]  is  a  pointer  to  the  first  argument. 
Because  of  the  limitations  in  Small-C, 
argv  must  be  declared  as  shown. 

The  library  also  provides  the  follow¬ 
ing  unbuffered  I/O  primitives.  These 
primitives  work  just  the  same  as  the  prim¬ 
itives  in  the  BDS  C  Library. 

close  (fd) 
int  fd; 

Closes  a  file  which  was  opened  by  open() 
or  creat( ).  Returns  -1  on  an  error. 

creat  (filename) 
char  *  filename; 

Creates  an  empty  file.  The  file  is  erased  if 
it  exists.  The  file  is  opened  for  reading  or 
writing.  Returns  a  file  descriptor  (a  short 
integer)  which  is  used  by  the  read(), 
write  (),  seek(),  tell  ( ),  close  (),  and 
fabortf)  routines. 

fabort  (fd) 
int  fd ; 

Frees  the  file  descriptor  fd  without  clos¬ 
ing  the  file.  Don’t  use  the  fabortQ  on  a 
file  which  was  open  for  writing  unless 
you  are  willing  to  lose  data  which  were 
written  into  it. 

open  (filename,  mode) 
char  *  filename; 
int  mode; 

Opens  a  file  for  reading  (mode  0),  writing 
(mode  1),  or  both  reading  and  writing 
(mode  2).  The  file  must  already  exist;  -1 
is  returned  if  it  doesn’t.  Returns  a  file 
descriptor  on  a  successful  open. 

read  (fd,  buffer,  nbl) 
int  fd; 

char  *  buffer; 
int  nbl; 

Reads  nbl  sectors  of  the  file  whose  file 
descriptor  is  fd  into  the  buffer.  All  sec¬ 
tors  are  128  bytes  in  the  CP/M  world,  re¬ 
gardless  of  their  actual  size  on  your  disk. 
Returns  the  number  of  blocks  actually 
read,  or  -1  for  errors.  0  means  end  of  file. 

rename  (oldname,  newname) 
char  *  oldname,  *  newname; 

Renames  the  file. 

seek  (fd,  n,  code) 
int  fd,  n,  code; 

Positions  the  file  for  reading  or  writing  at 
a  particular  sector.  Positions  the  file  at 
the  nth  sector  if  code  is  0.  Positions  the 
file  n  sectors  past  the  present  sector  if 
code  is  1 .  Returns  -1  on  a  seek  for  a  non¬ 
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existent  sector.  Make  sure  to  close  the  file 
if  seek  fails;  the  file  is  sure  to  be  in  bad 
shape. 

tell  (fd) 
int  fd; 

Returns  the  current  position  of  the  file 
(an  integer).  The  first  sector  of  the  file  is 
sector  0. 

write  (fd,  buffer,  nbl) 
int  fd ; 

char  *  buffer; 
int  nbl; 

Writes  nbl  sectors  from  the  buffer  to  the 
file.  Returns  -1  on  an  error,  which  is  usu¬ 
ally  caused  by  the  disk  becoming  full. 

unlink  (filename) 
char  *  filename; 

Erases  the  file  (permanently!)  from  the 
disk.  Use  with  caution. 

Finally,  the  new  library  provides  two 
functions  which  allow  jumps  between 
procedures.  This  is  a  very  important  capa¬ 
bility  to  have  for  error  recovery. 

setjmp  (buffer) 
char  buffer  [6]  ; 
longjmp  (buffer,  val) 
char  buffer  [6] ; 
int  val ; 

Setjmp ()  saves  the  current  state  of  the 
processor  in  the  buffer.  (For  Small-C 
this  means  the  BC  register,  the  program 
counter,  and  the  stack  pointer.)  SetjmpO 
itself  always  returns  0,  but  see  below. 
Whenever  a  later  call  to  longjmp  ()  is 
made  (from  anywhere  in  the  current 
function  or  a  lower-level  function)  the 
CPU  state  is  restored  to  what  it  was  when 
setjmpO  was  called  last  with  the  same 
buffer  argument.  The  program  behaves 
as  if  control  were  returning  from  the 
setjmpO  function  except  that  the  return 
value  is  the  “val”  which  was  passed  to 
longjmp  (). 

Ideas  for  Improving  the  Editor 

Nothing  is  impossible  for  the  man  who 
doesn ’t  have  to  do  it  himself. 

—  Weiler’s  Law 

The  algorithms  presented  last  month 
are  the  best  that  I  know  of;  I  would  like 
to  hear  about  any  improvements  that  you 
might  have.  Of  course,  improvements  to 
the  editor  are  possible.  Here  is  a  short  list. 

Rewriting  functions  in  assembly  lan¬ 
guage  is  an  obvious  way  to  increase  speed 
by  10%  to  100%.  The  swap_in(),  b_scan(), 
and  bufgetln()  routines  would  be  my 
candidates  for  recoding  because  they  are 
used  so  often.  It  is  likely  that  other 
routines  would  also  benefit  from  being 
written  in  assembly  language. 

Another  idea  is  to  change  the  format 
of  the  data  area  of  a  block.  Instead  of 
preceding  each  line  with  a  count,  it  is 


possible  to  create  a  table  of  pointers  to 
the  start  of  each  line.  This  table  would 
make  searching  in  the  b_scan()  routine 
unnecessary.  Dave  Cortesi  discussed  this 
idea  and  others  at  length  in  Dr.  Dobb’s 
Clinic  ( DDJ  No.  65,  March  1982,  pages 
6-9).  Putting  such  a  table  in  each  block 
will  slow  down  the  insert  and  delete 
operations  because  the  table  must  be 
adjusted.  However,  that  penalty  is  slight 
and  the  gain  to  be  had  from  speeding  up 
b_scan()  is  much  larger. 

Perhaps  the  most  interesting  improve¬ 
ment  to  the  editor  would  be  to  add  multi¬ 
ple  windows  to  the  screen.  The  new  buffer 
routines  could  be  modified  easily  to  deal 
with  multiple  files.  The  idea  is  to  have  all 
files  share  the  same  set  of  buffers;  all  that 
must  be  done  to  change  from  one  file  to 
another  is  to  swap  out  all  the  dirty 
blocks.  Of  course,  such  a  change  would 
require  a  major  revision  to  the  window 
module  on  file  red4.se. 

RED  and  Copyright 

I  think  it  is  important  to  distribute 
source  code  for  virtually  all  programs. 
Just  as  I  used  the  code  in  the  “Just  Like 
Mom’s”  editor  as  a  starting  point,  I  hope 
some  of  you  will  take  these  routines  and 
use  them  in  new  ways. 

RED  is  copyrighted  solely  to  protect 
myself  against  those  who  distribute  RED 
without  permission.  I  hope  you  will  feel 
free  to  do  anything  with  this  editor  ex¬ 
cept  distribute  it  for  profit.  Please  don’t 
let  the  copyright  prevent  you  from  using 
the  code;  if  you  are  unsure  about  how  I 
may  react  to  your  plans,  just  give  me  a 
call.  I’m  sure  we  can  work  something  out. 
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RED  -  Listing  (Text  begins  on  page  62) 

Listing  One 


RED  main  program  --  small-C  version 

Source :  r ed2 . sc 

Version:  January  22,  1983 

Copyright  (C)  1983  by  Edward  K.  Ream 


•  Define  the  disk  recovery  point.  •/ 
char  D_ERROR  [6]; 


/•  the  main  program  dispatches  the  routines  that 
•  handle  the  various  modes. 


•define  CMNDMODE  1  /•  enter  command  mods  flag  •/ 

•define  INSMODE  2  / •  enter  insert  modes  flag  •/ 

•define  EDITMODE  3  /•  enter  edit  mode  flag  •/ 

•define  EXITMODE  n  /•  exit  editor  flag  •/ 

main(  ) 

I 


i nt  mode ; 

/•  ready  the  system  module  •/ 
sysinitC ) ; 

/•  clear  the  main  buffer  •/ 
bufnew( ) ; 

/•  fir. t  output  by  default  goes  to  screen  •/ 
fmtassn(NO); 

/•  set  tabs,  clear  the  screen  and  sign  on  •/ 

fmtsett  8 ) ; 

outclr ( ) ; 

outxy(0,  SCR  ML  1 ) ; 

mes  sa  g e ( S IC NON  )  ; 

message! VERSION) ; 

message(COPYRIGHT); 

mes  sage( "" ) ; 

message(XSIGN); 

message(XSIGN1  )  ; 

out  xy(  0,  1  )  ; 

/•  clear  filename  []  for  save!),  resavef)  •/ 
pm  tc  1  r  (  ) ; 

/  *  start  off  in  command  mode  •/ 
modes  CMNDMODE ; 


/•  get  null  line  1  for  edit()  •/ 
edget 1 n ( ) ; 

whiled  )( 

if  (mode  s  s  EXITMODE)  { 
break; 

) 

else  if  (mode  xz  CMNDMODE)  ( 
modezcommand  (  )  ; 

) 

else  if  (mode  zz  EDITMODE)  { 
modesed i t( ) ; 

) 

else  if  (mode  z=  INSMODE)  ( 
mode=insert( ) ; 

1 

else  { 

syserr ( "main :  no  mode"); 


) 


modesEDITMODE  ; 


} 


*  handle  edit  mode . 

•  dispatch  the  proper  routine  based  on  one-character  commands. 

•/ 


ed  i  t  (  ) 

( 

char  buffer  (SCRNW1); 
i  nt  v ; 

i nt  x  ,y ,  topline  ; 
char  c; 

/•  we  can't  do  edgetln()  or  edgo()  here  because 
•  those  calls  reset  the  cursor. 

•/ 


/•  Set  disk  error  recovery  point.  •/ 
set  jmp( D_E  RROR ) ; 

pmted 1 1 (  )  ; 

whi  1  e  (  1  )  { 

/•  get  command  •/ 
c:tolower(syscin( )) ; 

/•  comment  out - 9/1**/82 

if  (c  ==  3)  i 

buf  d  ump( ) ; 

) 

-----  end  comment  out  •/ 


if  ( 


(c  ==  ESC  1 )  '  (css'c1  )  )  I 

/•  enter  command  mode.  •/ 
return  CMNDMODE; 


) 

else  if  (  (c  ==  INS  1 )  ;  (c=  s  •  i •  )  )  { 

/•  enter  insert  mode  •/ 
return  INSMODF ; 

) 

else  if  (special(c)  YES)  { 

if  (  (c  ==  UP  1 )  I  (c  ==  DOWN1)  )  { 
return  INSMODE; 

) 


) 

else  if  (control(c)  =x  YES)  ( 
continue ; 

) 

else  if  ( c  zs  •  ' )  ( 

edr  ight (  )  ; 
pmtcol ( ) ; 

) 

el se  if  ( c  zz  • b' )  ( 

edbegin(  )  ; 
pmtcol ( ) ; 

} 

else  if  ( c  z  z  •  d  ’  )  1 

/•  scroll  down  •/ 
pm tmod e ( "ed i t :  scroll"); 
syswait(  ) ; 

while  (bufnrbot()  zz  NO)  { 


if  (chkkeyO  ==  YES)  { 
break ; 

) 

eddn(  ) ; 

) 

pmtedit( ) ; 

} 

else  if  (c  zz  ’e')  l 
ede  nd  (  )  ; 
pmtcol (  )  ; 

) 

else  if  ( c  ==  ' g' )  l 

/•  save  x , y  in  case  don't  get  number  •/ 
xzoutgetx  (  )  ; 
y zoutgety (  )  ; 

pmtcmnd ( "ea i t :  goto:  ".buffer); 
i f ( number! buf fer  , & v)  )  ( 
edgo( v , 0) ; 

) 

el  se  ( 

outx  y ( x  ,y) ; 

) 

pmted it(  ) ; 

) 


else  if  ( c  zz  '  h '  )  { 

/•  remember  how  screen  was  drawn  */ 
x  zoutgetx (  ) ; 
y  =  outget y (  )  ; 
toplinezbufln!  )  —  y ♦  1  ; 

/•  output  the  help  message  •/ 

outclr ( ) ; 

out x  y  (  0,  SCRNL 1 )  ; 

edi thelp(  )  ; 


/•  redraw  the  screen  •/ 
bufout(topline, 1.SCRNL1); 
outx y ( x  ,y) ; 
pmted i t ( ) ; 


else  if  (c  zz  'k* )  { 

pmtmodef "edit:  kill"); 
czsyscin!  )  ; 

if  (  ( special ( c)  zz  NO)  & 

(control(c)  zz  NO) 

)  ( 

edkill(c); 

) 

pmted i t (  ) ; 

) 

else  if  (c  zz  's'  )  ( 

pm tmode ( "ed i t :  search"); 
czsyscin!  ) ; 

if  (  (special ( c)  zz  NO)  & 
(control(c)  zz  NO) 

)  ( 

edsrch( c ) ; 

1 

pmted i t () ; 

) 

el  se  if  ( c  x  z  • u'  )  ( 

/•  scroll  up  •/ 
pmtmode ( "ed i t :  scroll"); 
syswait(  )  ; 


} 

else  if 


while  (bufattop!)  zz  NO)  ( 

if  ( chkkey (  )  zz  YES) 
break ; 

} 

edup( ) ; 

) 

pmtedit( ) ; 

(  c  z  z  '  x  '  )  { 

pm tmod e ( " ed i t :  exchange"); 
czsyscin!  ) ; 

if  (  (special(c)  zz  NO)  & 

( control ( c )  zz  NO) 

)  ( 

edchng( c) ; 


( 
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else  if  (c  ==  UP2 )  { 
/*  move  up  */ 
ed  up (  )  ; 
pmtl i ne (  ) ; 
return  YES; 


/*  do  nothing  if  command  not  found  */ 


else  if  (  c  ==  U P 1  )  { 
/*  insert  up 
ed  newup ( ) ; 
pmtl i ne ( ) ; 
return  YES; 


/*  insert  mode . 

*  in  this  mode  the  UP1,  UP2  keys  reverse  their  roles, 
«  as  do  the  DOWN!,  and  DOW  N2  keys. 


if  (c  ==  DOW  N2 )  { 
/*  move  down  */ 
edd  n ( ) ; 
pmtl i ne ( ) ; 
return  YES; 


/•  Set  disk  error  recovery  point.  •/ 
set  jmp( D_E  RROR ) ; 

pmtmodeC " insert" )  ; 

while  ( 1 )  { 

/*  get  command  */ 
c=syscin(  )  ; 
if  ( c  ==  ESC  1  )  { 

/*  enter  command  mode  */ 
return  CMNDMODE; 

) 

else  if  ( c  =  =  EDIT1 )  { 

/•  enter  edit  mode  */ 
return  EDITMODE; 

} 

else  if  ( c  =  =  I  NS  1  )  { 

/•  do  nothing  •/ 


else  if  (special(c)  =  =  YES)  { 

if  (  (c  =  =  UP2)  !  (c  =  =  DOW N2 )  )  { 
return  EDITMODE; 

} 

el  se  { 

continue ; 


else  if  (control(c)  =  =  YES)  { 

/*  ignore  non-special  control  chars  •/ 
continue; 


/•  insert  one  char  in  line  */ 
edins(c) ; 
pmtcol ( ) ; 


if  (c  ==  DOW  N 1 )  { 

/*  insert  down  */ 
ednewdn( ) ; 
pmtl ine ( ) ; 
return  YES; 

if  (c  ==  LEFT1)  { 
edleft( ) ; 
pmtcol ()  ; 
return  YES; 

if  ( c  ==  RIGHT1 )  { 
edr ight ( ) ; 
pmtcol ( ) ; 
return  YES; 


command!)  dispatches  command  routines  while 
in  command  mode. 


command ( ) 
t 

i nt  v ; 

char  c ; 

char  args  [SCRNW1]; 

char  *argp; 

int  topline  ; 

int  ypos; 

int  oldl i ne  ; 

int  k ; 

/*  command  mode  commands  may  move  the  current  line. 

•  command  mode  must  save  the  current  line  on  entry 

*  and  restore  it  on  exit. 

•/ 

edr epl ( )  ; 

/*  remember  how  the  screen  was  drawn  on  entry  •/ 
o Id  1 i ne  =  buf 1 n (  )  ; 
y pos=outgety(  )  ; 
topline=oldline-ypos+1 ; 


/•  return  YES  if  c  is  a  control  char  •/ 

control(c)  char  c; 

{ 

if  (c  =  =  TAB)  { 

return  NO;  /•  tab  is  regular  •/ 

) 

else  if  (0  =  127)  ( 

return  YES;  /•  del  or  high  bit  on  */ 


else  if  (c  <  32)  ( 

return  YES;  /•  control  char  •/ 


handle  the  default  actions  of  all,,  special  keys, 
return  YES  if  c  is  one  of  the  keys. 


/*  Set  disk  error  recovery  point.  */ 
set  jmp ( D_E RROR ) ; 

whi le (  1  )  { 

sy swa i t (  ) ; 
o u t  x  y ( 0 , SCRNL1  )  ; 
f m  tc  r  1  f  (  )  ; 

pmt mo de(" command:"); 
getcmnd ( args , 0 ) ; 
fmtcr If ( ) ; 
pmtl i ne ( ) ; 
c=args  [ 0] ; 

i f  (  (c  ==  EDIT1 )  !  (c=  =  INS1  )  )  { 

/*  redraw  screen  •/ 

if  ( old  1 i ne  ==  bufln(  ))  ( 

/•  get  current  line  */ 
edgetln (  )  ; 

/•  redraw  old  screen  •/ 
bufoutC  topline , 1 , SCRNL  1  )  ; 
outxy(0, ypos)  ; 
s  yswa i t (  ) ; 


special ( c)  char  c; 


/•  update  line  and  screen 
edgo(bufln( ) ,0); 
syswa i t(  ) ; 


if  (c  ==  JOIN  1  )  ( 

ed  joi n (  )  ; 
pmtl i ne (  )  ; 
return  YES; 

) 

if  (c  ==  SPLT1)  { 
edspl i t (  )  ; 
pmtl i ne (  )  ; 
return  YES; 

) 

if  (  c  ==  A BT 1 )  { 
edabt( ) ; 
pmtcol  ( )  ; 
return  YES; 

) 

else  if  (c  ==  DELI)  { 
eddel ( ) ; 
pmtco 1 ( ) ; 
return  YES; 

) 

else  if  ( c  ==  Z  A  P 1 )  { 
e  d  z  a  p  (  )  ; 
pmtl i ne ( ) ; 
return  YES; 


==  EDIT1)  { 

return  (EDITMODE); 


return  (INSMODE); 


else  if  (  tolower  ( args  [0])  ==  'g'H 
argp=skipbl(args+1 ); 
if  ( argp  [0]  ==  EOS)  { 

edgo(oldline ,0) ; 
return  EDITMODE; 

} 

else  if  ( numbe r ( a rgp , & v )  ==  YES)  l 
edgo( v ,0) ; 
return  EDITMODE; 


message("bad  line  number"); 


(Continued  on  page  70) 
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RED  -  Listing 

(Listing  continued,  text  begins  on  page  62) 


k-- ; 

J  =  0; 

while  ( j  <  k)  l 

outcharCargs  [j++]); 

} 


if  (  lookup( args , "append"  )  )  ( 
a  ppend ( args  )  ; 

if  (lookup(args, "change"))  { 
change (args) ; 

if  (  lookup( args , "clear"  ) )  ( 

clear ( ) ; 

if  (  lookup( args ,  "copy"))  { 
copy ( args ) ; 

if  (lookup(args." delete"))  { 
delete(args) ; 

if  (  lookup( args , "dos" ) )  ( 
i f  ( chkbuf ( )  ==  YES)  { 

/•  clean  up  any  temp  files.  •/ 
buf  end ( ) ; 

return  (EXITMODE); 

1 

if  (lookup(args,"find"))  l 
if  ( (k  s  f ind( ) )  >=  0)  l 
edgo( buf In ( ) , k ) ; 
return  EDITMODE; 


else  if  (c  s  =  A BT 1 )  { 

outxy(offset,outgety(  ))  ; 

outdeol ( ) ; 

k»0; 

) 

else  if  ( ( c  Is  TAB)  A  ((c  <  32 ) 1 < c  ==  127)))  l 
/•  do  nothing  */ 
continue; 

) 

el  se  { 

if  ( k+off set  <  SCRNW1)  ( 
args  [  k-#-  +  ]  =c  ; 
o  ut  cha  r ( c )  ; 


args  [k]=E0S; 


RED  command  mode  commands  —  small-C  version 


So  urce :  red  3 • sc 

Version:  January  23.  1983;  February  26,  1983 


Copyright  (C)  1983  by  Edward  K.  Ream 


/*  get  current  line  •/ 
buf go(oldline)  ; 
e dgetl n (  ) ; 

/*  stay  in  command  mode  •/ 
messaget "pattern  not  found"); 


/•  Define  data  global  to  these  routines.  •/ 
char  filename  [ S YSFNMAX ] ; 


if  (lookup(args.  "help"))  ( 
hel p( ) ; 


if  (  lookup( a rgs , " 1 i st " ) ) 
1  ist( args) ; 


if  (  lookup ( arg s ," load" ) ) 
load(args); 


if  (  lookup( args , "move" ) ) 
novel args) ; 


if  (  lookup( args name" ) ) 
name ( args ) ; 


if  (  lookup( args ," resave" ) 
r esave ( ) ; 


if  (  lookup( args save" ) ) 
save! ) ; 


if  ( lookup! args search" ) 
search(args); 


if  (  lookup! args ," tabs" ) ) 
tabs! args) ; 


if  (  lookup! args ,"") )  { 


message! "command  not  found"); 


/•  return  YES  if  line  starts  with  command  •/ 


Append  command . 

Load  a  file  into  main  buffer  at  current  location. 
This  command  does  NOT  change  the  current  file  name. 


append (args) 
char  *args; 

{ 


char  buffer  [MAXLEN];  /•  disk  line  buffer  •/ 
int  file; 
i  nt  n ; 

int  topline; 

char  locfn  [SYSFNMAX];  /•  local  file  name  */ 

/•  Get  file  name  which  follows  command.  •/ 
if  ( name  1 ( a rgs , loc f n )  ==  ERR)  { 
return ; 

) 

if  (locfn  [0]  =  =  EOS)  { 

message! "no  file  argument"); 
return  ; 

> 

/•  Open  the  new  file.  •/ 

if  ((file  =  sysopen! locfn .  0))  ss  ERR)  l 
message (" fi 1 e  not  found"); 
return ; 

) 

/•  Read  the  file  into  the  buffer.  •/ 
while  ( (n=sysrdln( file .buffer .MAXLEN) )  >=  0)  { 
if  (n  >  MAXLEN)  ( 

message! "1 ine  truncated"); 
bufdump( ) ; 
e  x  i  t  (  ) ; 
n=M AXLEN ; 

) 

bufins(buffer.n); 
buf  dn (  ) ; 


lookup! line  .command )  char  •line,  *command; 

( 

while(#command)  { 

if  ( tolower ( • 1 i ne+ ♦  )  Is  *command  +  +  )  ( 
return  NO; 

) 


if!  (Mine  ss  EOS)  !  (Mine  =  = 
return  YES; 


•)  !  (Mine  =  =  TAB)  )  l 


/ •  Close  the  file. 
sysclose( f ile) ; 


Redraw  the  screen  so  topline  will  be  at  top 
of  the  screen  after  command!)  does  a  CR/LF. 


topline=max( 1 ,bufln( )-SCRNL2); 
buf  out ( topline ,2, SCRNL2)  ; 


buf go (topline) ; 


/  *  get  next  command  into  argument  buffer  •/ 
getcmnd f arg s . of f set )  char  "args;  Int  offset; 


int  j  ,  k  ; 
char  c ; 


outxy(offset,outgety(  ))  ; 
outdeol () ; 
ks  0 ; 

while  ( ( c: s ysc i n (  ) )  Is  CR)  { 

if  (  (c  ss  EDIT1)  !  (c  s  =  I  NS  1  )  )  f 

args  [ 0]sc; 
return ; 

) 

IT  (  (c  ss  DELI)  !  (c  ==  LEFT  1 )  )  { 
if  ( k>  0  )  { 

outxy( offset. outgety!  )); 
outdeol ( )  ; 


/•  Global  change  command.  */ 

change! args) 
char  *args; 

l 

char  oldline  [MAXLEN1];  /•  reserve  space  for  EOS  */ 

char  newline  [  M  A  XL  E  N  1  ]  ; 

char  oldpat  [ M AXLE N 1 ] ; 

char  newpat  [ M AXLE N 1 ] ; 

int  from,  to,  col,  n,  k; 

/*  Check  the  arguments.  •/ 
if  ( ge 1 2a r gs ( a rgs , & f rom , & to )  ss  ERR)  1 
return  ; 

) 

/•  get  search  and  change  masks  into  oldpat,  newpat  • 
f mtsout ( " sea rch  mask  ?  ",0); 

getcmnd(oldpat,  15); 
f  mtc  r 1 f (  )  ; 
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if  (oldpat  [0]  ==  EOS)  { 
return  ; 

} 

pmtl i ne ( ) ; 

fmt so ut( "change  mask  ?  n,0); 

getcmnd ( newpat , 15) : 
fmtcr  1  T(  )  ; 

/*  make  substitution  for  lines  between  from,  to  •/ 
whi le  ( f rom  <=  to)  l 

if  ( chkkey ( )  ==  YES)  { 
break; 

) 

buf go( from**)  ; 
iT  ( buf  a  tbot ( )  ==  YES)  { 
break ; 

} 

n=bufgetln(oldline, MAXLEN); 
n  =  m  i  n  ( n  .MAXLEN)  ; 
old  1 i ne  [ n ] =  EOS ; 

/•  anchors  search  */ 

if  (oldpat  [0]  ==  '“')  { 

if  ( amatchC old  1 i ne , oldpat* 1 , 0  )  ==  YES)  { 
k=replace(oldline, newline, 
oldpat+1 .newpat ,0)  ; 
if  (k  rr  ERR)  { 
return  ; 

I 

fmtcrlf ( ) ; 
putdec(bufln( )  ,5); 
fmtsout( newline, 5); 
outdeol ( ) ; 
bufrepl(newline.k); 


co n t i nue  ; 

} 

/•  search  oldline  for  oldpat  •/ 

col *0 ; 

while  (col  <  n)  ( 

if  ( amatch( old  1 ine , old  pa t ,  co  1**  )  ==  YES)( 
k=replace(oldline, newline, 

oldpat, newpat, col-1); 
if  (k  =  =  ERR )  ( 
return ; 

} 

f  mtcr 1 f ( ) ; 
putdec(bufln( ) ,5); 
fmtsout(newline,5); 
o  utdeol ( ) ; 
bufrepl( newline ,k) ; 
break; 


> 

f  mtc  r 1 f ( ) ; 


/•  clear  main  buffer  and  file  name  •/ 
clear  (  ) 

l 

/•  make  sure  it  is  ok  to  clear  buffer  •/ 
if  (chkbufO  ==  YES)  { 
filename  [ 0  ]  =  0 ; 
pmtf i le ( "" ) ; 
outclr (  ) ; 
outx  y ( 0 , SCRNL 1 ) ; 

buf  new ( ) ; 

message( "buffer  cleared"); 


/*  Block  copy  command.  •/ 

copy(args) 
char  •  args; 

{ 

int  i  ,  k  ; 
i nt  last; 

int  fstart,  fend,  tstart; 
char  buffer  [MAXLEN1]; 

/•  Get  exactly  three  args.  •/ 

if  (get3args(args,  4 fstart,  A  fend,  4 tstart)  ==  ERR)  { 
return  ; 


} 


The  'to'  and  'from'  blocks  must  not  overlap. 
Fstart  must  be  >  0,  tstart  must  be  >=  0. 

•/ 

i f  (  ( f end  <  f start)  i 

(fstart  <=  0)  ! 

(tstart  <0)  ', 

(  (tstart  >=  fstart)  4  (tstart  <  fend)  ) 

)  l 

mes sag e ( "oo ps  .  check  the  copy  parameters"); 
return  ; 

} 


/*  Make  sure  the  last  line  exists.  */ 
last  =  max(tstart,  fstart); 

buf  go ( last ) ; 


i f  ( buf ln( )  f  =  last)  1 

message( "Last  line  doesn't  exist."}; 
return; 

} 


Move  the  'from  block'  to  the  'to  block'. 
Move  one  line  at  a  time. 

•/ 

i  =  0; 

while  (i  <=  fend  -  fstart)  { 

/*  Go  to  next  line  of  'from  block'.  */ 
if  (fstart  <  tstart)  { 

buf  go ( f  star t  ♦  i ) ; 

} 

else  { 

buf go( fstart  ♦  i  ♦  i ) ; 

} 

if  (bufatbotO)  { 

/ •  end  of  'from  block'  •/ 
break  ; 

) 

/•  Get  line  of  'from  block'  into  buffer.  •/ 
k  =  buf getln( buf fer ,  MAXLEN); 

/*  Go  to  next  line  of  'to  block'.  •/ 
buf go( tstart  ♦  i  ♦  1  )  ; 

/•  Insert  next  line  into  'to  block'.  */ 
buf i ns ( buffer  ,  k); 

/•  Bump  the  count.  */ 


/*  multiple  line  delete  command  •/ 

delete( args) 
char  ‘args  ; 

l 

int  f r om ,  to ; 

/•  Check  the  request.  •/ 
if  ( get  2a r gs( arg s , & f rom ,4  to )  ==  ERR)  { 
return  ; 

) 

i f  ( from  >  to)  { 
return  ; 

) 

/•  go  to  first  line  to  be  deleted  •/ 
buf  go( from ) ; 

/•  delete  all  lines  between  from  and  to  */ 
bufdeln(to-from*1); 

/•  redraw  the  screen  */ 
buf  out ( bufln( ) . 1 , SCRNL 1 ) ; 

} 

ed i the  1 p(  ) 

{ 

message ( 

"Here  is  a  list  of  the  commands  that  you  can  use  in  edit  mode." 

);  message( 

"Control  characters  (preceeded  by  “)  may  also  be  used  in  insert  mode." 
);  message! 

"Type  help  when  in  command  mode  for  a  list  of  command  mode  commands." 

);  message! 

);  message! 

"b  beginning  of  line  “d 

);  messagef 

"c  or  ESC  enter  command  mode  “e 
);  message( 

"d  scroll  down  “h 

);  message( 

"e  end  of  line  “1 

);  message! 

"g<n>  go  to  line  <n>  “p 

) ;  message ( 

"h  print  this  message  “r 

);  message! 

"i  or  "n  enter  insert  mode  “s 
) ;  message ( 

"k  <  let>  delete  to  <let>  ‘u 

) ;  message ( 

"s  <let>  set  cursor  to  <let>  “x 
)  ;  message ( 

"u  scroll  up  “z 

)  ;  messa ge ( 

"carriage  return:  insert  line  below  current  line;  enter  insert  mode" 

);  message! 

"line  feed:  insert  line  above  current  line;  enter  insert  mode" 

) ;  message! 

)  ;  message! 

"Type  any  character  to  continue  editing...  " 

)  ; 

pm  ted i t ( ) ; 
syscin!); 

} 


move  cursor  up;  enter  edit  r.cde 

enter  edit  mode" 

delete  character" 

move  cursor  left" 

join  two  lines" 

move  cursor  right" 

split  line  at  cursor" 

move  cursor  up;  enter  edit  node 

undo  changes  to  the  line" 

delete  line" 


( Continued  on  next  page) 
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(Listing  continued,  text  begins  on  page  62) 

'•  search  all  lines  below  the  current  line  for  a  pattern 

*  return  -1  if  pattern  not  found. 

*  column  number  of  start  of  pattern. 


1 n ( )  ♦  1.  HUGE.  YES); 


r.e  :  pv  ) 


message 

"Here  is  a  list  of  commands  you  can  use  in  command  mode." 

)  ;  -essagei 

"~yje  h  when  in  edit  mode  for  more  help." 

;  e  s  s  a  g  e  ; 

;  r  e  s  s  a  b  e  l 

"append  <filename>  append  a  Tile  after  the  current  line" 

'  ;  z  es  sage  ( 

range  <line  range>  change  all  lines  in  <line  range)" 

;  ressagei 

"clear  reset  the  editor" 

'  ;  message ( 

"copy  •.nl>  <n2>  <n3>  copy  lines  <nl>  through  <n2>  after  <n3>" 

;  -essagei 

"delete  <line  range)  delete  all  lines  in  <line  range)" 

5  ;  rr.  e  s  s  a  g  e  ( 

"do s  exit  from  the  editor" 

;  ;  r,  e  s  s  a  g  e  t 

"fir.j  search  for  a  pattern;  Enter  edit  mode  if  found" 

;  r  e  5  s  a  g  e  v 

"g  <rr.)  enter  edit  mode  at  line  <n>" 

)  ;  rressagev 

"g  :r  ‘e  enter  edit  mode  at  the  current  line" 

;  messaged 

"help  print  this  message" 

:  ressageC 

"list  list  lines  to  the  printer" 

;  message ( 

"lead  <filer,ame>  replace  the  buffer  with  <filename>" 

)  ;  message 

"move  (n1)  <n2>  <n3>  move  lines  <n1>  through  <n2)  after  <n3>" 

;  messaged 

"name  <filename>  set  the  filename  for  the  save  and  resave" 

'  ;  message 

"resave  save  the  buffer  to  the  already  existing  file" 

.  ;  message 

"save  save  the  buffer  to  a  new  file" 

:  r.  essageC 

"search  list  all  lines  which  contain  a  pattern" 

;  message' 

"taps  <r. >  set  tabs  to  every  <n>  columns" 


/*  list  lines  to  list  device  */ 

1  i s  t ( a  r  g  s' 
char  *args; 

I 

char  linebuf  [ M  AXLEN  1  ]  ; 

i  nt  n ; 

int  from,  to,  line,  oldline; 

*  save  the  buffer's  current  line  •/ 
o!dline=bufln( ) ; 

*  get  starting,  ending  lines  to  print  */ 
if  ge 1 2ar gs( arg s , & f r om . & to )  ==  ERR)  { 

return  ; 

} 

*  print  lines  one  at  a  time  to  list  device  •/ 

lines  from ; 

while  (line  <=  to)  l 

/*  maKe  sure  prompt  goes  to  console  */ 
f m ta  s  sn ( NO ) ; 

/*  check  for  interrupt  */ 
if  (chkkeyO  =s  YES)  { 
break ; 

) 

/*  print  line  to  list  device  */ 
fmta  ssn ( YES  ) ; 

bufgo(  line+4- )  ; 
i f  ( buf a tbot ( ) )  { 
break; 

) 

n  =  bufgetln( linebuf, MAXLEN1); 
nsmin ( n  .MAXLEN ) ; 
linebuf  [n]=CR; 
f mtsout ( linebuf, 0); 
f mter If ( ) ; 


/*  redirect  output  to  console  »/ 
fmtassn(NO); 


/•  restore  cursor  •/ 
bufgo(oldline) ; 


/*  Load  file  into  buffer.  •/ 

load  (args) 
char  *args ; 

{ 

char  buffer  [MAXLEN];  /•  disk  line  buffer  */ 
Char  loefn  [SYSFNMAX];  /•  file  name  •/ 
int  n ; 

int  topline; 

/•  Get  filename  following  command.  •/ 
if  ( name  1 ( args , loc fn )  »  ERR)  { 

return  ; 

) 

if  (loefn  [0]  *s  EOS)  { 

message("no  file  argument"); 
return  ; 

) 

/•  Give  user  a  chance  to  save  the  buffer.  •/ 
if  (chkbufO  =s  NO)  [ 
return  ; 

) 

/•  Open  the  new  file.  •/ 

if  ( sysex i s ts( loc f n )  ::  NO)  { 

mes sage ( " f i 1 e  not  found"); 
return ; 

} 

/•  Update  file  name.  •/ 
s yscopf n (  loc f n  ,  filename); 
pmtfile( filename) ; 

/•  Clear  the  buffer.  */ 
buf  ne w( ) ; 

/ •  Read  the  whole  file  into  the  buffer.  •/ 
buf_r_f i le( filename) ; 

/•  indicate  that  the  buffer  is  fresh  •/ 
b uf  sa  ved (  ) ; 

/•  set  current  line  to  line  1  */ 
buf go( 1 ) ; 

/• 

Redraw  the  screen  so  that  topline  will  be 
on  line  1  after  commandt)  does  a  CR/LF. 

•/ 

top  lines max(1,bufln()-SCRNL2); 
buf  out ( topline, 2, SC RNL2); 
buf  go( topline) ; 


/•  Block  move  command.  •/ 

move( args) 
char  *  args; 

{ 

int  c  ,  i  ,  k ; 
int  last; 

int  fstart,  fend,  t3tart; 
char  buffer  [MAXLEN1]; 

/•  Get  exactly  three  args.  •/ 

if  ( get3»rgs( args ,  ifstart,  ifend,  Atstart)  ::  ERR)  [ 
return ; 

) 


The  'to'  and  'from'  blocks  must  not  overlap. 
Fstart  must  be  )  0,  tstart  must  be  >s  0. 

•/ 

if  (  (fend  <  fstart)  ! 

(fstart  <=  0)  j 
(tstart  <  0)  ! 

(  (tstart  >s  fstart)  &  (tstart  <=  fend)  ) 

)  ( 

message("oops.  check  the  move  parameters"); 
return  ; 

) 

/•  Make  sure  the  last  line  exists.  •/ 
if  (tstart  <  fstart)  { 
last  s  f start ; 

} 

else  { 

last  x  tstart; 

) 

buf go( last)  ; 
if  ( buf ln(  )  ! =  last)  ( 

return  ; 


Move  the  'from  block'  to  the  'to  block*. 
Move  one  line  at  a  time. 

«/ 

i  s  c  s  0; 

while  ( c* ♦  <=  fend  -  fstart)  { 

/*  Go  to  next  line  of  'from  block' .  */ 
buf  go ( fstart  ♦  i )  ; 

i f  ( buf  a  tbo t (  )  )  { 

/•  end  of  'from  block'  */ 
break  ; 

} 
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/*  Get  line  of  'from  block'  into  buffer.  "/ 
k  =  b uf ge t 1 n ( buf f er ,  MAXLEN); 

/•  Delete  this  line.  *f 
bufdeln(  1  )  ; 

/•  Go  to  next  line  of  'to  block'  .  *  / 
if  (tstart  <  fstart)  { 

/*  Delete  leaves  'to  block'  numbers.  */ 
bufgo(tstart  +  i  ♦  1); 


/*  Delete  decreased  numbers  by  one.  * / 
buf  go(  tstart  i  )  ; 


/"  Insert  next  line  into  'to  block', 
buf  i  ns(  buffer ,  k)  ; 


/*  Adjust  line  numbers  if  needed, 
if  (tstart  <  fstart)  { 


/•  Line  numbers  increase. 


/*  Write  out  the  whole  buffer.  *  / 
b uf_w_f il e (filename); 

/*  Indicate  buffer  saved.  •/ 
buf  saved ()  ; 

/*  Restore  line  number.  */ 
bufgo(oldline)  ; 

} 

/*  global  search  command  "/ 

searcht args) 
char  *args  ; 

{ 

int  from ,  to  ; 

/*  Check  the  request.  "/ 
if  (  get2a r gs( args , & from  ,& to )  ==  ERR)  { 
return ; 

) 

sea rch 1 ( from  ,  to,  NO); 


/*  search  lines  for  a  pattern. 

*  if  flag  ==  YES:  stop  at  the  first  match. 

*  return  -1  if  no  match. 

#  otherwise  return  column  number  of  match. 

•  if  flag  ==  NO:  print  all  matches  found. 


/•  change  current  file  name 


name(args) 
char  'args ; 


nameKargs,  filename)  ; 
pmtfile( filename) ; 


check  syntax  of  args. 
copy  to  f i lename . 

return  OK  if  the  name  is  valid. 


sea r ch 1 ( f rom ,  to,  flag) 
int  from ,  to ,  flag ; 

{ 

char  pat  [MAXLEN1];  /•  reserve  space  for  EOS 
char  line  [MAXLEN 1 ] ; 
int  col ,  n ; 

/*  get  search  mask  into  pat  •/ 
fmtsout( "search  mask  ?  ",0); 

get  cmnd ( pat , 1 5 ) ; 
fmtcrlf ( ) ; 


if  (pat  [0]  ==  EOS)  { 
return  - 1 ; 


/*  bug  fix  */ 


nameKargs,  filename) 
char  'args,  "filename; 

{ 

/•  skip  command  "/ 
args=skiparg(args) ; 
argsiski pbl ( args) ; 

/•  check  file  name  syntax  "/ 
if  ( syschkfn( args)  s=  ERR)  { 
return  ERR ; 

) 

/•  copy  filename  •/ 
syscopfn(args, filename)  ; 


/*  Save  the  buffer  in  an  already  existing  file.  •/ 


resave( ) 

{ 


int  n  ,  oldline ; 


/•  Save  line  number.  •/ 
oldline  =  buf 1 n ( ) ; 


/•  Make  sure  file  has  a  name.  •/ 
if  (filename  [0]  ==  EOS)  { 

messa ge ( " f i 1 e  not  named"); 
return  ; 


/•  The  file  must  exist  for  resave.  •/ 
if  ( syse x i s t s ( f i 1 ename )  ==  NO)  { 

message( "file  not  found"); 
return ; 


/•  Write  out  the  whole  buffer, 
buf  w  file( filename) ; 


/•  Indicate  that  the  buffer  has  been  saved, 
buf  saved ( ) ; 


/*  search  all  lines  between  from  and  to  for  pat  •/ 
whi  le  ( from  <=  to)  { 

if  ( chkkey (  )  ==  YES)  { 
break ; 

} 

buf  go ( f  rom* ♦ )  ; 
i f  ( buf atbot(  )  ==  YES)  { 
break  ; 

} 

n  =  bufgetln(  line  .MAXLEN)  ; 
n  =  min ( n  .MAXLEN  )  ; 
line  [ n ] =EOS ; 

/•  “  anchors  search  •/ 
if  (pat  [0]  ==  '“')  { 

if  ( amatch( line , pa t* 1 , 0  )  ==  YES)  { 
if  (flag  ==  NO)  { 
f  mtcr 1 f (  ) ; 
putdec(bufln(  )  ,5); 
f  mtsout ( line  ,  5  )  ; 
o  utd  eo 1 (  )  ; 

) 

else  { 

return  0 ; 

) 

) 


/•  search  whole  line  for  match  •/ 
col  =  0 ; 

while  (col  <  n)  { 

if  ( amatch( line , pa t . col*  ♦  )  ==  YES)  [ 
if  (flag  ==  NO)  { 
f mtcr 1 f (  )  ; 


putdec( buf ln( )  .5  )  ; 
f  mtsout ( 1 ine , 5  ) ; 
outdeoK  )  ; 
break  ; 


return  col-  1  ; 


/*  Restore  line  number, 
buf go ( ol d 1 i ne  )  ; 


/*  Save  the  buffer  in  a  new  file. 


in',  file,  n,  oldline; 

/•  Save  current  line  number.  */ 
old  line  =  buf ln( ) ; 

/"  Make  sure  the  file  is  named.  */ 
if  (filename  [0]  ==  EOS)  { 

mes  sa  ge  (  "  f  i  1  e  not  nar.ed"); 
return ; 

1 

/•  File  must  NOT  exist  for  save.  •/ 
if  ( sys e x i s t s ( f i 1 ename )  ==  YES)  { 
messageC'file  exists"); 
return ; 


/*  all  searching  is  finished  */ 
if  (flag  ==  YES)  { 
return  - 1 ; 

) 

else  { 

fmtcrlf ( ) ; 

} 


/*  set  tab  stops  for  fmt  routines  */ 


tabs(args) 
char  "args; 

{ 

int  n  ,  j  unk ; 


if  ( ge 1 2a r g s( a rg s , & n , & junk)  ==  ERR)  l 
return  ; 


( Continued  on  next  page) 
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(Listing  continued,  text  begins  on  page  62) 


} 


/•  return  YES  if  buffer  may  be  drastically  changed  */ 

chkbuf ( ) 

{ 

if  ( buf c hng ( )  ==  NO)  { 

/*  buffer  not  changed,  no  problem  •/ 
return  YES; 

} 

f mtsout ( "buf f er  not  saved,  proceed  ?  ",0); 

pmtl i ne ( ) ; 

if  ( tolower ( syscout( sysci n( ) ) )  !=  *  y  '  )  1 

f  mtc  r  1  f  (  )  ; 

message! "cancelled") ; 
return  NO; 

1 

else  ( 

f  mtc r 1 f (  )  ; 
return  YES; 

) 


) 

/*  print  message  from  a  command  •/ 

message! s) 
c  ha  r  •  s  ; 

{ 

fmtsout! s  ,0) ; 
fmtcrlf ( ) ; 

) 

/•  get  two  arguments  the  argument  line  args. 

*  no  arguments  imply  1  HUGE. 

*  one  argument  implies  both  args  the  same. 

*/ 

get2args(args,val 1 ,val2) 

char  *args; 

int  "vail,  • val2 ; 

l 

/*  skip  over  the  command  •/ 
args  =  skiparg(args)  ; 
args=skipbl(args) ; 

if  ( 'args  r  s  EOS)  { 

•  va  1 1  =  1 ; 

•  va  1  2  =  H  UG  E  ; 
return  OK; 

) 

/•  check  first  argument  •/ 
if  ( numbe r ( a r g s , v a  1 1 )  s:  NO)  | 

message! "bad  argument"); 
return  ERR  ; 

1 

/*  skip  over  first  argument  •/ 
args=ski parg! args) ; 
a  rg  s: ski pbl ( a  rgs ) ; 

/•  1  arg:  arg  2  is  HUGE  •/ 
if  (*args  ==  EOS)  { 

•val2=HUGE  ; 
return  OK; 

} 

/•  check  second  argument  •/ 
if  ( numbe r ( args , val 2 )  *=  NO)  { 

message! "bad  argument"  )  ; 
return  ERR; 

) 

else  ( 

return  OK; 

) 


/•  Get  exactly  three  arguments.  */ 

ge  t -a  rg  s  (  a  rg  s  ,  vail,  val2,  val3) 
char  *args; 

ir.t  "vail,  *val2,  •  v  a  1  3  I 

{ 

/*  Skip  the  command.  •/ 
args  s  skiparg  (args); 
args  =  skipbl  (args); 

/•  Check  first  arg.  •/ 
if  Cargs  *=  EOS)  | 

message! "missing  arguments"); 
return  ERR  ; 

) 

if  (number  (args,  vail)  :s  NO)  l 
message! "bad  argument"); 
return  ERR; 

) 

/*  Skip  over  first  argument.  •/ 
args  =  ski parg! args)  ; 
args  =  ski pbl ( args) ; 
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/  *  the  entire  pattern  matches  •  / 
return  YES; 


replace  oldpat  in  oldline  by  newpat  starting  at  col. 


put  result  in  newline. 

return  number  of  characters  in  newline. 


replacet oldline  .newline  .oldpat .newpat .col ) 
char  •oldline,  •newline,  •oldpat,  "newpat; 
i n t  col; 

l 

int  k  ; 

char  fltail,  •pat; 

/•  copy  oldline  preceding  col  to  newline  •/ 
k  =  0 ; 

while  ( k  <  col )  { 

newline  [ k**  ]  =  *old 1 i ne*+ ; 

} 

/•  remember  where  end  of  oldpat  in  oldline  is  •/ 
tai l  =  old line  ; 
pat  =  o Id  pa  t ; 

while  ( • pat**  !  =  EOS)  ( 
tai 1**  ; 


edchng(c)  char  c; 

{ 

char  oldc; 
int  k ; 


/•  if  at  right  margin  then  insert  char  •/ 
if  (editp  >=  editpmax)  { 
ed i ns ( c ) ; 
return  ; 

} 

/•  change  char  and  print  length  of  line  •/ 

oldc  =  edi  tbuf[  editp] ; 

editbuf[editp]  =  c; 

fmtadjteditbuf, editp, editpmax); 

k  =  f m tl en ( ed i tbuf , ed i tp*  1  ) ; 

if  (k  >  SCRNW1 )  { 

/•  line  would  become  too  long  •/ 

/•  undo  the  change  •/ 
editbuf [edi tp]  =  oldc; 
fmtadjteditbuf, editp, editpmax) ; 


/•  set  change  flag,  redraw  line  */ 

edcflag  =  YES; 

ed i tp**  ; 

edad j ( ) ; 

edredrawt  )  ; 


/•  copy  newpat  to  newline. 

•  use  oldline  and  oldpat  to  resolve  question  marks 

•  in  newpat . 


/•  delete  the  char  to  left  of  cursor  if  it  exists 


while  ('newpat  !=  EOS)  { 

if  (k  >  MAXLEN-1)  { 

message("new  line  too  long"); 
r  eturn  ERR  ; 

} 

if  ( *newpat  !=  '?')  { 

/•  copy  newpat  to  newline  •/ 
newline  [k*+]:§newpat*+; 
c  on  t i n ue  ; 


/•  just  move  left  one  column  if  past  end  of  line  •/ 
if  (edxposO  <  outgetxO)  l 

outx y( outgetx ()- 1 ,  outgetyO); 
return  ; 


/•  do  nothing  if  cursor  is  at  left  margin 
if  (editp  ==  0)  ( 


/•  scan  for  '?'  in  oldpat  •/ 
while  (*oldpat  !=  '?'•)  ( 

if  ( 'oldpat  ==  EOS)  { 
mes  sage ( 

"too  many  ?'s  in  change  mask" 

); 

return  ERR ; 

) 

oldpat**; 

oldline**; 


/•  copy  char  from  oldline  to  newline  •/ 

newline  [ k** ] ='oldl ine** ; 

oldpat**; 

newpat**; 


/•  copy  oldline  after  oldpat  to  newline  •/ 
while  ('tail  !=  EOS)  { 

if  (k  >=  MAXLEN-1 )  { 

messageC'new  line  too  long"); 
return  ERR ; 

) 

newline  ( k* ♦  ]  =  • ta i 1* ♦ ; 

) 

newl ine  ( k ] =E0S ; 


edcflag  =  YES; 

/•  compress  buffer  (delete  char)  •/ 
k  =  editp; 

while  (k  <  editpmax)  { 

editbuf[k-1]  =  editbuftk]; 
k**; 

) 

/•  update  pointers,  redraw  line  •/ 
edi tp-- ; 
edi tpmax--; 
edredraw( ) ; 


/•  edit  the  next  line.  do  not  go  to  end  of  buffer 
eddn(  ) 
l 

int  oldx; 

/•  save  visual  position  of  cursor  •/ 
oldx  =  outgetx ( )  ; 

/•  replace  current  edit  line  •/ 
edrepl  ( )  ; 

/•  do  not  go  past  last  non-null  line  •/ 
if  ( bufnr bot(  ) )  { 
return; 


RED  window  module  —  small-C  version 


/•  move  down  one  line  in  buffer  •/ 
buf  dn ( ) ; 
edgetln(  ) ; 

/•  put  cursor  as  close  as  possible  on  this 
•  new  line  to  where  it  was  on  the  old  line. 


Source:  red4.sc 

Version:  January  23.  1983 


Copyright  (C)  1983  by  Edward  K.  Ream 


/•  data  global  to  this  module  •/ 

char  editbuf[MAXLEN] ;  / 
int  editp;  / 
int  editpmax ;  / 
int  edc  f lag ;  / 


/•  the  edit  buffer  •/ 
/•  cursor:  buffer  index  •/ 
/•  length  of  buffer  •/ 
/•  buffer  change  flag  •/ 


/*  abort  any  changes  made  to  current  line  */ 
edabtf  ) 

{ 

/•  get  unchanged  line  and  reset  cursor  •/ 

edgetln(  )  ; 

edredrawt ) ; 

edbegin(  )  ; 

edcflag  ;  NO; 


editp  =  edscan( oldx ) ; 

/•  update  screen  •/ 
if  ( eda tbot (  ))  l 

edsup(bufln( )-SCRNL2); 
outx  y( oldx,  SCRNL1); 

) 

else  ( 

outxyt  old*  ,  outgety(  )♦  1  )  ; 

) 

return; 


/•  put  cursor  at  the  end  of  the  current  line  •/ 


editp  =  editpmax; 
edad  j ( )  ; 

outxy(edxpos( ) ,outgety(  ))  ; 


/*  put  cursor  at  beginning  of  current  line  •/ 

edbegin ( ) 

{ 

editp  =  0; 
outxy(0,outgety( ) ) ; 

} 

/•  change  ed i tbuf [ edi tp ]  to  c 
•  don't  make  change  if  line  would  become  to  long 


start  editing  line  n 

redraw  the  screen  with  cursor  at  position  p 


(Continued  on  next  page) 
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(Listing  continued,  text  begins  on  page  62) 


p)  int  n  ,  p ; 

/•  replace  current  line  */ 
edr epl ( ) ; 

/•  go  to  new  line  */ 
buf  go( n) ; 

/*  prevent  going  past  end  of  buffer  •/ 
i f  ( buf  a  tbot ( ) )  { 

buf  up (  )  ; 

} 

/*  redraw  the  screen  */ 
bufout  (  buf ln( ) , 1 , SCRNL  1  )  ; 
edgetln(  )  ; 

editp  =  min(p,  editpmax); 
outxy( edxpos( )  ,  1 ) ; 
return  ; 


/*  insert  c  into  the  buffer  if  possible 

ed i ns ( c ) 
char  c ; 

{ 


/*  do  nothing  if  edit  buffer  is  full  •/ 
if  (editpmax  >=  MAXLEN)  ( 
return  ; 

J 

/*  fill  out  line  if  we  are  past  its  end  •/ 
if  ((editp  ==  editpmax)  A  (edxpoaO  <  outgetxO))  t 
k  s  outgetxO  -  edxpos(); 
editpmax  s  editpmax  ♦  k; 
while  (k—  >  0)  { 

editbuf  [editp++]  s  ' 


/*  replace  lower  line  temporarily  •/ 
edrepl  ( )  ; 

/*  get  upper  line  into  buffer  */ 
buf up(  ) ; 

kl  =  buf getln( editbuf  ,  MAXLEN); 

/*  append  lower  line  to  buffer  */ 
buf dn ( ) ; 

k2  =  bufgetln(editbuf+k1 ,  MAXLEN-k 1 ) ; 

/•  abort  if  the  screen  isn't  wide  enough  •/ 
if  (kl  ♦  k2  >  SCR NW 1  )  { 

/•  bug  fix  •/ 

buf getln( editbuf, MAXLEN)  ; 

return ; 


/*  replace  upper  line  */ 
buf up( ) ; 

editpmax  s  kl  +  k 2 ; 
editp  s  kl  editp; 
edad J  ( ) ; 
edcflag  =  YES; 
edr epl ( ) ; 

/•  delete  the  lower  line  •/ 
buf  dn ( ) ; 
bufdel ( ) ; 
buf up(  ) ; 

/•  update  the  screen  */ 
if  ( eda ttop( ) )  { 

edredrawO; 

) 

else  { 

k  =  outgety ( )  -  1 ; 

buf out  (  bufln( ) , k , SCRNL-k ) ; 

outx  y( 0 , k )  ; 

edredrawt ) ; 

) 


/*  delete  chars  until  end  of  line  or  c  found  */ 


edkill(c)  char  c; 

{ 


/•  make  room  for  inserted  character  •/ 

k  :  edi tpmax ; 

whi le  (k  >  editp)  ( 

editbuf [k]  =  edi tbuf [ k-1  ) ; 
k  — ; 

) 

/*  insert  character,  update  pointers  */ 
editbuf[editp]  =  c; 
edi tp*4 ; 
edi tpmax++ ; 

/•  recalculate  print  length  of  line  •/ 
fmtadj(editbuf,editp-1 .editpmax) ; 
k  r  f mtlen ( edi tbuf ,ed i tp) ; 

if  (  (k  >  SCRNVM)  &  (editp  ==  editpmax)  )  { 

/•  auto-split  the  line  (line  wrap)  •/ 

/•  scan  for  the  start  of  the  current  word  •/ 
k  =  editp  -  1; 
while  (  (k  >=  0)  & 

(editbuftk]  Is  '  ')  & 

(editbuf[k]  Is  TAB) 

)  t 

k — ; 

) 

/*  never  split  a  word  */ 
if  (k  <  0)  l 

eddel ( ) ; 
return ; 


/•  do  nothing  if  at  right  margin  */ 
if  (editp  ss  editpmax)  { 
return  ; 

} 

edcflag  s  YES; 

/•  count  number  of  deleted  chars  •/ 
k  *  1; 

while  ((editp+k)  <  editpmax)  { 

if  (editbuf[editp+k]  ss  c)  { 
break ; 

) 

else  { 

k*  + ; 

) 

) 

/•  compress  buffer  (delete  chars)  •/ 

p  s  edi t p  +  k  ; 

while  (p  <  editpmax)  { 

editbuf[p-k]  s  editbuf[p); 


/•  update  buffer  size,  redraw  line  •/ 
editpmax  s  editpmax-k; 
edredraw( ) ; 


/*  move  cursor  left  one  column. 

•  never  move  the  cursor  off  the  current  line. 

•/ 


/*  split  the  line  at  the  current  word  •/ 
editp  s  k  +  1; 
edspl i t ( ) ; 
edend ( ) ; 

} 

else  if  (k  >  SCRNW1  )  { 

/•  line  would  become  too  long  */ 

/*  delete  what  we  just  inserted  */ 
eddel (  )  ; 


/•  set  change  flag,  redraw  line 
edcflag  =  YES; 
edr edr aw ( ) ; 


ed 1 e  f t ( ) 

I 

i nt  k ; 


/•  if  past  right  margin,  move  left  one  column  •/ 
if  (edxposO  <  outgetxO)  { 

outxy(max(0,  outget  x  (  )  -  1  )  ,  outgetyO); 

} 

/•  inside  the  line.  move  left  one  character  */ 
else  if  (editp  Is  0)  ( 
editp--; 

outxy(edxpos( ) ,outgety(  )); 

> 


insert  a  new  blanlr  line  below  the  current  line  */ 


/*  join  (concatenate)  the  current  line  with  the  one  above  it  •/ 

ed j  oi n (  ) 

{ 

int  k.  kl.  k2; 

/•  do  nothing  if  at  top  of  file  •/ 
if  (bufattopO)  { 
return ; 


ednewdn ( ) 

int  k ; 


/•  make  sure  there  is  a  current  line  and 
*  put  the  current  line  back  into  the  buffer. 
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if  (bufatbot())  i 

buf  ins(v.ji  tbuf, editpmax) ; 

) 

edrepl ( )  ; 

/*  move  past  current  line  •/ 
buf dn ( ) ; 

/•  insert  place  holder:  zero  length  line  */ 
bufins(editbuf.O); 

/*  start  editing  the  zero  length  line  •/ 
edgetln (  )  ; 

/•  update  the  screen  */ 
i f  ( edatbotl  )  )  { 

/•  note:  buflnO  >=  SCRNL  */ 
edsupt buf 1 n (  )-SCRNL2) ; 
outxy(edxpos( ) .SCRNL1 ) ; 


} 

else  { 

k  =  outgety ( ) ; 

b  uf  ou t ( buf 1 n ( ), k* 1 , SCRNL  1  -k ) ; 
outxy(edxpos( ) ,  k*  1 ); 


/•  insert  a  new  blank  line  above  the  current  line  •/ 

ednewup( ) 

( 

i  nt  k ; 

/•  put  current  line  back  in  buffer  •/ 
edrepl ( ) ; 

/•  insert  zero  length  line  at  current  line  •/ 
bufips(editbuf.O); 

/•  start  editing  the  zero  length  line  •/ 
edgetlnt  )  ; 

/•  update  the  screen  •/ 
if  (edattopO)  { 

edsdn ( buf 1 n ( ) ) ; 
outx  y ( edx  pos( ) , 1 ) ; 

} 

else  ( 

k  =  outgety ( ) ; 

buf  o  u  t ( buf 1 n ( ) , k , SCRNL-k ) ; 

outxy(edxpos(),k); 


/•  move  cursor  right  one  character. 

•  never  move  the  cursor  off  the  current  line. 

•/ 

edr ight(  ) 


/•  if  we  are  outside  the  line  move  right  one  column  */ 
if  (edxposf)  <  outgetxO)  { 

outxy  (min(SCRNW1,  outgetx ( )♦ 1 ) ,  outgetyO); 

) 

/*  if  we  are  inside  a  tab  move  to  the  end  of  it  •/ 
else  if  (edxposO  >  outgetxO)  { 

outxy  (edxposO,  outgetyO); 

) 


/•  move  right  one  character  if  inside  line  •/ 
else  if  (editp  <  editpmax)  { 
editp**; 
edad j ( )  ; 

outxy(edxpos( ) , outgety ( )) ; 

) 


1 


/•  else  move  past  end  of  line  •/ 
else  ( 

outxy  (min(SCRNW1,  outge  t  x  (  )  *  1  )  .  outgetyO); 

) 


/•  split  the  current  line  into  two  parts. 

•  scroll  the  first  half  of  the  old  line  up. 

*/ 


ed  sp 1  i  t (  ) 

{ 

i  nt 


i  nt 


P. 
k ; 


q ; 


/•  indicate  that  edit  buffer  has  been  saved  •/ 
edcflag  =  NO; 

/•  replace  current  line  by  the  first  half  of  line  */ 
if  (bufatbotO)  { 

buf i ns ( ed i tbuf  .  editp); 

) 

else  { 

buf repl ( ed i tbuf  ,  editp); 

) 


/•  redraw  the  first  half  of  the  line  •/ 

p  =  editpmax; 

q  =  editp; 

editpmax  =  editp; 

editp  =  0; 

edr edrawf ) ; 

/•  move  the  second  half  of  the  line  down  •/ 
editp  =  0; 
while  (q  <  p)  { 

editbuf  [editp*-*]  =  editbuf  [q**]; 

editpmax  =  editp; 
editp  =  0; 

/•  insert  second  half  of  the  line  below  the  first  •/ 
buf  dn ( ) ; 

buf ins( edi tbuf  .  editpmax); 

/*  scroll  the  screen  up  and  draw  the  second  half  */ 
i f  ( edatbotl ) )  l 

edsupt buflnC )-SCRNL2) ; 
outxyt 1 , SCRNL  1  )  ; 
edredraw( ) ; 

) 

else  { 

k  =  outgety () ; 

bufout<  buf  InO  ,  k*  1  ,  SCRNLI-k); 

outx  y( 1 ,  k*  1  ) ; 
edredrawt ) ; 


/•  move  cursor  right  until  end  of  line  or 
•  character  c  found. 

•/ 

edsrch(c)  char  c; 

l 

/•  do  nothing  if  at  right  margin  •/ 
if  (editp  ==  editpmax)  ( 
return  ; 

) 

/•  scan  for  search  character  •/ 
editp**; 

while  (editp  <  editpmax)  { 

if  ( editbufteditp]  *=  c)  ( 
break ; 

} 

else  { 


/•  reset  cursor  •/ 
edad j (  )  ; 

outxy(edxpos( ) ,outgety( ) ) ; 


/•  move  cursor  up  one  line  if  possible  •/ 

edup( ) 

( 

int  oldx ; 

/•  save  visual  position  of  cursor  •/ 
o  Id  x  =  outgetx () ; 

/•  put  current  line  back  in  buffer  •/ 
edr epl ( ) ; 

/•  done  if  at  top  of  buffer  •/ 
if  ( buf  a  ttop( ) )  ( 
return ; 

} 

/*  start  editing  the  previous  line  •/ 
buf up( ) ; 
edgetln(  )  ; 

/*  put  cursor  on  this  new  line  as  close  as 
possible  to  where  it  was  on  the  old  line. 

•/ 

editp  =  edscan ( old x ) ; 

/*  update  screen  •/ 
i f  ( edattop( ) )  { 

edsdn( buf ln( ) ) ; 
outxy(oldx,  1); 

) 

else  { 

outxy(oldx,  outgety( )-1 ) ; 

) 

return  ; 

) 

/•  delete  the  current  line  •/ 

ed  zap (  ) 

{ 

int  k  ; 

/•  delete  the  line  in  the  buffer  •/ 
buf  del ( ) ; 


/*  move  up  one  line  if  now  at  bottom  */ 
if  (bufatbotO)  { 


(Continued  on  page  82) 
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(Listing  continued,  text  begins  on  page  62) 


buf  up( ) ; 
edgetln ( ) ; 

/*  update  screen  */ 
if  ( eda t top (  ) )  { 

edredrawt ) ; 

) 

else  i 

outd el  In (  ) ; 
outxy(0,outgety(  )-1  ); 

) 

return  ; 


edrepl ( ) 

{ 

/*  do  nothing  if  nothing  has  changed  »/ 
if  ( edc  flag  ==  NO)  { 
return ; 

) 

/•  make  sure  we  don't  replace  the  line  twice  */ 
edc  flag  =  NO; 


) 


/•  insert  instead  of  replace  if  at  bottom  of  file  */ 
if  ( buf  a  tbot (  ) )  { 

bufins(editbuf, editpmax)  ; 

} 

else  ( 

bufrepl(editbuf, editpmax)  ; 

} 


/•  start  editing  new  line  */ 
edgetln (  )  ; 

/*  update  screen  */ 
i f  ( edattopC ) )  { 

ed  sup ( buf In ( ) ) ; 
outxy( 0,1); 

} 

else  l 

k  s  out  gety ( ) ; 

bufout( bufln( ) ,k,SCRNL-k) ; 

outxy( 0 , k) ; 

) 

) 


/*  - -  utility  routines  (not  used  outside  this  file)  -  •/ 


/*  set  editp  to  the  largest  index  such  that 
*  bufteditp]  will  be  printed  <s  xpos 
V 


edscan(xpos)  int  xpos; 

[ 


editp  r  0; 

while  (editp  <  editpmax)  { 

if  ( fmtlen ( edi tbuf , ed i tp)  <  xpos)  { 
edi tp++ ; 

) 

else  l 


editp; 


/*  adjust  the  cursor  so  it  stays  on  the  screen. 

*  call  this  routine  whenever  the  cursor  could  move  right. 


e  d  a  d  j  (  ) 
{ 


1 


while  ( fmtlen( edi tbuf .  editp)  >  SCRNW1)  { 
ed i tp-- ; 


} 


/*  return  true  if  the  current  edit  line  is  being 
*  displayed  on  the  bottom  line  of  the  screen. 


edatbotf  ) 

{ 

return  outgety()  ==  SCRNL1; 


/*  return  true  if  the  current  edit  line  is  being 
*  displayed  on  the  bottom  line  of  the  screen. 


edattop( ) 

{ 

return  outgety()  ==  1; 

) 


/•  redraw  edit  line  from  index  to  end  of  line  */ 
/*  reposition  cursor  * / 
edredrawl  ) 

t 

fmtadj(editbuf,0, editpmax)  ; 
fmtsubs(editbuf,max(0,editp-1),editpmax); 
outxy(edxpos( ) ,outgety(  ))  ; 

) 


/•  return  the  x  position  of  the  cursor  on  screen  •/ 

edx  pos (  ) 

{ 

return  fmtlen ( ed i tbuf  ,  editp); 

} 


/•  fill  edit  buffer  from  current  main  buffer  line. 

*  the  caller  must  check  to  make  sure  the  main 

*  buffer  is  available. 

•/ 

edgetin( ) 

{ 

int  k ; 

/  •  put  cursor  on  left  margin,  reset  flag  •/ 
editp  *  0; 
edcflag  s  NO; 

/•  get  edit  line  from  main  buffer  */ 
k  r  bufgetln(editbuf.MAXLEN)  ; 
if  (k  >  MAXLEN)  { 

error("line  truncated"); 
editpmax  =  MAXLEN; 

) 

else  ( 

editpmax  =  k; 

) 

f  mtad  j ( ed i tbuf , 0 , editpmax); 

) 

/•  Replace  current  main  buffer  line  by  edit  buffer. 

*  The  edit  buffer  is  NOT  changed  or  cleared. 


/•  scroll  the  screen  up.  topline  will  be  new  top  line  •/ 

edsup( topline)  int  topline; 

( 

if  (outhasupO  3=  YES)  { 

/*  hardware  scroll  */ 
outsup(  ) ; 

/•  redraw  bottom  line  */ 
bufout(topline+SCRNL2,SCRNL1, 1  ); 

1 

else  { 

/•  redraw  whole  screen  */ 
bufout(topline, 1.SCRNL1); 


/*  scroll  screen  down.  topline  will  be  new  top  line  */ 

edsdn( topline)  int  topline; 

{ 

if  (outhasdnO  ==  YES)  { 

/•  hardware  scroll  */ 
out sdn (  )  ; 

/*  redraw  top  line  •/ 
bufout(topline,1,  1); 

) 

else  ( 

/•  redraw  whole  screen  •/ 
bufout(topline.l.SCRNLI); 


RED  output  format  module  --  small-C  version 

Source :  red5 . sc 

Version:  August  21,  1982. 

Copyright  (C)  1983  by  Edward  K.  Ream 

•/ 

/*  Define  variables  global  to  this  module.  */ 

/•  define  maximal  length  of  a  tab  character  */ 
int  fmttab ; 


/*  define  the  current  device  and  device  width  •/ 

int  fmtdev;  /•  device  --  YES/NO  =  LIST/CONSOLE  */ 

int  fmtwidth;  /•  devide  width.  L1STU/SCRNU J  •/ 


fmtcol[i]  is  the  first  column  at  which 
buf[i]  will  be  printed. 

fmtsub()  and  fmtlen()  assume  fmtcolH  is  valid  on  entry. 


int  fmtcol[MAXLEN  1  ]  ; 


Direct  output  from  this  module  to  either  the  console  or 
the  list  dev  ice  . 

*/ 

fnlassnt listflag)  int  listflag; 
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if  (  listflag==YES)  { 
f  m td  e  v  =  Y  ES  ; 
f mtwidth=L ISTW  ; 


fmtdev=NO; 
f mtwi d  thrSCRNW  1  ; 


Adjust  fmtcol[]  to  prepare  for  calls  on 
fmtoutC)  and  fmtlenC). 

NOTE:  this  routine  is  needed  as  an  efficiency 

measure.  Without  fmtadjC),  calls  on 
fmtlenC)  become  too  slow. 


f mtad j ( buf . m in i nd .max i nd )  char  *buf;  i nt  mi n i nd .max i nd ; 


/•  line  always  starts  at  left  margin  */ 
fmtcol[0]=0; 

/*  start  scanning  at  minind  */ 
ksminind ; 

while  ( k<  max i nd )  ( 

/*  comment  out  - 

if  ( buf  [ k ] ==CR )  l 
break ; 

I 

-  end  comment  out  •/ 


Output  one  character  to  current  device. 
Convert  tabs  to  blanks. 


fmtoutch(c.col)  char  c;  int  col; 

{ 

int  k ; 

if  (c==TAB)  { 

k=fmtlench(TAB,col) ; 
while  ( ( k--  )  >  0 )  l 
fmtdevch(' 

} 

) 

else  if  (c<32)  { 

f  mtdevch( ' * ' ) ; 
fmtdevchC  c+6*i ) ; 


f  mtdevch( c ) ; 


/*  Output  character  to  current  device.  */ 


f mtco 1 [ k  +  1  ]=fmtcol[k]+fmtlench(  buf[k]  , f  mtcol [ k ]  )  ; 


/*  return  column  at  which  at  which  buf[i]  will  be  printed  •/ 
fmtlen( buf , i )  char  "buf;  int  i; 


returnC  fmtcol[i] ); 


fmtdevch(c)  char  c; 

( 

if  ( fmtdev==YES)  { 

sysloutC c  &  127); 

) 

else  l 

outchar(c  &  127); 

} 


/•  Output  a  CR  and  LF  to  the  current  device.  */ 


Print  buf[i]  ...  buf[j-1]  on  current  device  so  long  as 
characters  will  not  be  printed  in  last  column. 


fmtsubs( buf , 1  ,  j  )  char  *buf;  int  i,  j; 

( 

int  k ; 

<r  (  fmteol[ i ] >  =  fmtwidth)  { 
return  ; 


out x y( f mtcol [ i ], outgetyC )) ;  /•  p 

while  (i<J)  { 

/*  Comment  out  - 

i f  ( buf [ i ] ==CR)  { 
break  ; 

) 

- —  end  comment  out  •/ 

if  ( fmtcolt W 1  )>fmtwidth)  { 
break  ; 

) 

fmtoutch(buf[i],fmtcol[i]  ); 


/•  position  cursor 


f m  tc  r  1  f  (  ) 

l 


if  C fmtdev==YES)  { 

sysloutC CR) ; 
syslout(LF) ; 


/*  kludge:  this  should  be  in  out  module  */ 
/•  make  sure  out  module  knows  position  */ 
out  x  y  (  0  .  SCRNL1  )  ; 
syscout  (  CR  ) ; 
syscout(LF)  ; 


/*  Set  tabs  at  every  n  columns. 

fmtset(n)  int  n; 

{ 

fmttabr  max ( 1 , n ) ; 

} 


/•  clear  rest  of  line  •/ 


Print  string  which  ends  with  CR  or  EOS  to  current  device. 
Truncate  the  string  if  it  is  too  long. 


RED  terminal  output  module 
Source :  red6 . sc 

This  file  was  created  by  the  configuration  program: 
January  20.  1983;  February  26.  1983 

Modified  by  hand:  gotoxy(),  outdeolC). 


fmtsout ( buf , of f set )  char  *buf;  int  offset; 

{ 

char  c; 
int  co 1  ,  k  ; 

col  =  0 ; 

whi  le  (  c  = "buf ♦♦ )  ( 

if  (e==CR)  ( 

break; 

l 

k=fmtlench(c,col); 
if  ( ( col+k+off set) >fmtwidth)  { 
break; 

) 

f mtoutch( c  ,col ) ; 
col  =  col  +  k  ; 


Define  the  current  coordinates  of  the  cursor. 


int  outx ,  outy ; 


Return  the  current  coordinates  of  the  cursor. 


outgetx  (  ) 

{ 

returnC  outx ) ; 


/•  Return  length  of  char  c  at  column  col.  */ 

fmtlenchC c ,col )  char  c;  int  col; 

{ 

if  (c==TAB)  l 

/*  tab  every  fmttab  columns  • 
returnC  fmttab-(colXfmttab) )  ; 

} 

else  if  Cc<32)  l 

/•  control  char  •/ 
returnC 2 ) ; 

) 

else  ( 

returnC 1 ) ; 


outgety C ) 

l 

returnC  outy) ; 

) 


Output  one  printable  character  to  the  screen. 


outchar(c)  char  c; 

{ 

sy scout  C  c  ) ; 
outx*-*; 
r  et  ur  n  C  c ) ; 


(Continued  on  next  page) 
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(Listing  continued,  text  begins  on  page  62) 

Position  cursor  to  position  x,y  on  screen. 

0.0  is  the  top  left  corner. 

•  / 

outxy( x  ,  y )  i nt  x  ,  y  ; 

{ 

syscout ( 11); 
s  yscout  (  6  4*y  )  ; 
s yscout ( 1 6) ; 

syscout!  ((x/10)««)  i  (xXIO)  ); 

out  X: X ; 
outy=y ; 


Erase  the  entire  screen. 

Make  sure  the  rightmost  column  is  erased. 


outclr ( ) 

i 

i  nt  k  ; 
k  =  0 ; 

while  (k<SCRNL)  ( 

outxy( 0 , k*  + ) ; 
outdel ln( ) ; 

1 

outxy!  0,0); 

1 


Delete  the  line  on  which  the  cursor  rests. 
Leave  the  cursor  at  the  left  margin. 


outdelln( ) 

1 

outxy(O.outy) ; 
outdeol ( ) ; 

) 


/•  Initialize  the  mode  and  file  name.  •/ 
pmtclr ( ) 

l 

pmtln  [0]  s  0; 
pmtfn  [0]  s  0; 

) 


/• 

Put  error  message  on  prompt  line. 
Wait  for  response. 

•/ 

pmtmess! si , s2) 
char  'si,  •  s2 ; 

1 

int  x.y; 

/•  save  cursor  •/ 
xsoutgetx ( ) ; 
ysoutgety! ) ; 
out  x  y ( 0 , 0  ) ; 

/•  make  sure  line  is  correct  */ 
outdel  ln(  )  ; 
pmtl i ne 1 ( ) ; 
pmtcol 1 ( x ) ; 

/•  output  error  message  •/ 

fmtsout(s1,outgetx()); 

fmtsout(s2,outgetx()); 

/•  wait  for  input  from  console  •/ 
syscin! ) ; 

/•  redraw  prompt  line  •/ 
pmtl  i  ne  1  (  ) ; 
pmtcol 1 ( x  ) ; 
pmtf i le 1 ( pmtf  n ) ; 
pmtmode 1 ( pmtln ) ; 

/•  restore  cursor  •/ 
out xy ( x.y); 

) 


/■  Write  new  mode  message  on  prompt  line.  •/ 


Delete  to  end  of  line. 

Assume  the  last  column  is  blank. 


outd eo  1  (  ) 

{ 

syscout ( 27  )  ; 
syscout( 'K  '  ) ; 


yes  if  terminal  has  indicated  hardware  scroll. 


outhasup!  ) 


} 


return! YES) ; 


pmtmode! s) 
char  • s ; 

{ 

int  x.y;  /•  save  cursor  on  entry  •/ 

/•  save  cursor  •/ 
xsoutgetx! )  ; 
ysoutgety!  ) ; 

/•  redraw  whole  line  •/ 

outxy(O.O); 

outdel In! ) ; 

pmtl  i  ne  1  (  ) ; 

pmtcol 1 ( x ) ; 

pmtf i lei! pmtfn ) ; 

pmtmode  1  ( s ) ; 

/•  restore  cursor  •/ 
out  x  y ( x  ,  y ) ; 

) 


outhasdn! ) 

return!YES); 

1 


Scroll  the  screen  up. 

Assume  the  cursor  is  on  the  bottom  line. 


c  u  t  s  u  p !  ) 

/•  auto  scroll  •/ 
outxy!0,SCRNLl  )  ; 
syscout ( 10); 

) 


Scroll  screen  down. 

Assure  the  cursor  is  on  the  top  line. 


/•  Update  file  name  on  prompt  line.  •/ 

pmtf i le ! s) 

char  •  s ; 

1 

int  x ,  y ; 

/•  save  cursor  •/ 
xsoutgetx ! )  ; 
ysoutgety!  ) ; 

/*  update  whole  line  •/ 
out  x  y!  0 , 0 ) ; 
outdel In!  )  ; 
pmtl 1 ne 1 ! ) ; 

pmtcol 1 ( x ) ;  /•  bug  fix  —  1/28/82  •/ 

pmtf i le 1 ! s) ; 
pmtmode 1 ( pmtl n ) ; 

/•  restore  cursor  •/ 

outxy! i,y) ; 

} 


/•  Change  mode  on  prompt  line  to  edit:  •/ 


/•  auto  scroll  */ 
outx  y ( 0 . 0) ; 
syscout(27); 
syscout! ' 1 1 ) ; 

/*  19.2  Kbaud  kludge  •/ 
wait  s  0; 

while  wait**  <  I'jO)  1 


pmtedit!  ) 

{ 

pmtmode ( "edit:"); 

> 


/•  Update  line  and  column  numbers  on  prompt  line.  •/ 

pm tl i ne !  ) 

{ 

int  x.y; 


RED  prompt  line  module  --  small-C  version 

Source  :  r ed7 . sc 
Version:  August  2**,  1982. 

Copyright  ( C )  1983  by  Edward  K.  Ream 

•/ 

/*  Define  the  prompt  line  data.  */ 

char  pm tl n [ M AXLEN ] ;  /*  mode  •/ 

char  pmtfnt SYSFNMAX  ) ;  /•  file  name  •/ 


/*  save  cursor  */ 

xsoutgetx!); 

ysoutgety!); 

/•  redraw  whole  line  •/ 

out  x  y  (  0 , 0  ) ; 

outdel In!  ) ; 

pmtlinel!); 

pmtcol 1 ! x  ) ; 

pmtf i 1 e 1 ( pmtfn ) ; 

pmtmode  1( pmtln)  ; 

/•  restore  cursor  */ 
outxy! x  ,  y) ; 
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Return  larger  of  two  numbers. 


/*  Update  just  the  column  number  on  prompt  line.  */ 


max  (  a ,  b ) 
i nt  a ,  b ; 

{ 

if  (a  >=  b)  { 

return  a ; 

} 

else  { 

return  b; 

) 

} 


/•  save  cursor  •/ 
x  rout  get x ( ) ; 
y=outgety( } ; 

/•  update  column  number  •/ 
pmtcol 1 ( x ) ; 

/*  update  cursor  •/ 
outxy( x , y ) ; 


Return  smaller  of  two  numbers.  */ 


min( a  ,  b) 
i  nt  a  ,  b ; 
{ 


if  (a  <=  b)  { 

return  a; 


/•  Update  mode.  call  getcmnd()  to  write  on  prompt  line.  *  / 

pmtcmnd(mode .buffer) 
char  ‘mode ,  “buffer; 

l 

int  x , y ; 

/•  save  cursor  */ 
xr out ge t x  (  )  ; 
y  =  outgety(  ) ; 
pmtmode 1 ( mode ) ; 

/•  user  types  command  on  prompt  line  */ 
getcmnd( buffer ,outgetx(  )  ); 

/•  restore  cursor  •/ 

/*  - —  new  - 

out  x  y  (  x  ,  y  )  ; 

-  end  comment  out  */ 


Return  the  absolute  value  of  a  number.  •/ 


if  (n  <  0)  { 

return  -n; 

) 

else  { 

return  n; 

} 


Convert  a  character  to  lower  case. 


/•  Update  and  print  mode.  */ 

pmtmode 1 ( s ) 
char  “s ; 

I 

int  i  ; 

outxy(JJO.O); 
f  mtsout ( s . ) ; 
i  =  0; 

while  ( pm tl n[ i* ♦ ] = “s* * )  { 


tol ower ( c ) 
char  c; 

{ 


if  (  (c  >=  'A' )  &  (c  <=  'Z '  )  )  { 
return  c  -  ' A '  ♦  ' a ' ; 

) 

else  { 

return  c; 

) 


return:  is  first  token  in  args  a  number 
return  value  of  number  in  “val 


/*  Print  the  file  name  on  the  prompt  line.  •/ 

pmtfilel(s) 
char  *  s  ; 

( 


outxy(25,0)  ; 
if  ( *  s  =  =  EOS  )  ( 

f  mtsout( "no  file", 25); 


fmtsout( s  .25)  ; 


i  =  0 ; 

while  (pmtfn[ i++]:*s++)  { 


number ( arg s . val )  char  “args;  int  “val; 
char  c; 

cs*args++; 

if  ((c<'0')i(c>'9’))  { 
return(NO) ; 

• valsc- 'O'; 

while  (cs*args++)  { 

if  ( ( c< ' 0  '  ) ! ( c>  •  9  ' )  )  { 
break  ; 

) 

•val:  (*val*10)*c-  'O'  ; 

) 

ret ur n ( Y  ES  ) ; 


/•  Convert  character  buffer  to  numeric.  */ 


/*  Print  the  line  number  on  the  prompt  line.  •/ 

pmtl i ne 1 ( ) 

{ 

outx  y( 0 , 0  ) ; 
fmtsout("line:  ",0>; 
putdec ( buf ln(  )  ,5  ) ; 

) 

/*  Print  column  number  of  the  cursor.  */ 

pmtcol 1  (  x) 
int  x  ; 

( 


ctoi ( buf , index )  char  *buf;  int  index; 

I 

int  k ; 

while  (  ( buf [ i ndex ] == '  ')  | 

( buf [ index ] ==TAB)  )  { 
index** ; 

) 

k=  0 ; 

while  (( buf[ index ]>=' 0 ')&( buf [ i ndex ]<=' 9 ')  )  { 
k: (k*10)+buf[ index]-' 0  '  ; 
index**; 

} 

return(k) ; 

} 


/•  comment  out  all  the  following  code  if  you  do  not 

•  want  column  numbers  to  be  drawn  on  the  screen. 

•  some  people  complain  of  too  much  flicker. 

•/ 

out  x  y ( 12,0); 

fmtsout( "column:  ",12); 

putdec ( x  ,  3  )  ; 


RED  general  utilities  --  small-C  version 


Source :  r ed9 • sc 

Version:  August  27,  1982. 


Copyright  (C)  1  983  by  Edward  K.  Ream 


Put  decimal  integer  n  in  field  width  >=  w. 
Left  justify  the  number  in  the  field. 


putdec ( n  ,w )  int  n , w ; 

{ 

char  chars[ 1 0] ; 
int  i , nd ; 

nd  =  i to c(n,  chars, 10); 

i  =  0; 

whi le  ( i<  nd  )  { 

syscout(chars[i**]  ); 


i  =  nd ; 

while  ( i**<w)  { 

syscout (  '  '  )  ; 


(Continued  on  next  page) 
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RED  ■  Listing 

(Listing  continued,  text  begins  on  page  62) 


•  Convert  integer  n  to  character  string  in  str.  •/ 
itoc( n ,str .size)  int  n;  char  »str;  int  size; 


i  r. :  a  b  s  v  a  1  ; 
int  len  ; 
int  i  ,  j , k  ; 

absval:abs( n)  ; 

/•  generate  digits  */ 
str  [  0  JsO  ; 
is  1 ; 

whl le  (  i<size)  { 

str[i  +  +  ]s(absval%l0)-»'0'  ; 
absval=absval/10; 
if  (absval==0)  { 


/•  generate  sign  •/ 
if  ( ( i < s i ze ) 4 ( n<0))  l 
str[ i*+]s ; 

) 

len  =  i-  1  ; 

/*  reverse  sign,  digits  •/ 
i--; 

J  *  0 ; 

while  (j<i)  | 

k=str[  i]  ; 
str[ i ] sstr[ J)  ; 
str[ j  ]  s  k ; 

i  — ; 
i*+ : 

} 

return (  len  )  ; 


*  System  error  routine.  •/ 
syse-r ' s)  char  *s; 

pmtmess( "system  error:  ",s); 


*  .ser  error  routine.  •/ 
e  -  r  5  r  :  s '  c  h  aV  •  s  ; 

pr.tmess(  "error  :  ",s); 


Listing  Two 


End  Listing  One 


CCXOR : 


;  "And" 
CCAND: 


;  Test 
CCEO: 


;  Test 
CCNE : 


;  Test 
CCLE: 


;  Test 
CCGE  : 


;  Test 
CCLT: 


MOV 

A  ,  L 

XRA 

E 

MOV 

L  .A 

MOV 

A  ,  H 

XRA 

D 

MOV 

RET 

H  .A 

HL  and 

DE  into  HL 

MOV 

A  ,  L 

ANA 

E 

MOV 

L  ,  A 

MOV 

A  ,  H 

ANA 

D 

MOV 

RET 

H  .A 

if  HL  * 

DE  and  set  HL 

CALL 

RZ 

CCCMP 

DCX 

RET 

H 

if  DE  - 

r  HL 

CALL 

RNZ 

CCCMP 

DCX 

RET 

H 

if  DE  > 
XCHG 

HL  (signed) 

CALL 

RC 

CCCMP 

DCX 

RET 

H 

if  DE  <  =  HL  (signed) 

CALL 

RZ 

RC 

CCCMP 

DCX 

RET 

H 

if  DE  > 

z  HL  (signed) 

CALL 

RNC 

Acmp 

DCX 

RET 

H 

if  DE  < 

HL  (signed) 

CALL 

RC 

CCCMP 

DCX 

RET 

H 

1  if  true  else  0 


Common  routine  to  perform  a  signed  compare 
of  DE  and  HL 

This  routine  performs  DE  -  HL  and  sets  the  conditions: 

Carry  reflects  sign  of  difference  (set  means  DE 
Zero/non-zero  set  according  to  equality. 


CCCMP: 

MOV 

A  ,  E 

SUB 

L 

MOV 

E  ,  A 

MOV 

A.D 

SBB 

H 

LX  I 

H  .  1 

ipreset  true 

condition 

JM 

CCCMP 1 

ORA 

E 

;"OR"  resets 

carry 

RET 

CCCMP1 : 

ORA 

E 

STC 

;set  carry  to 

signal  minus 

RET 

i'a  sm 

Part  I  of  the  Small-C  Run-time  Library 
Functions  called  from  the  code  generators 

Source :  1  lb  1 

Version:  August  5.  1982 


;Fetch  a  single 

byte  from 

the  address  in  HL  and 

RC 

;  sign  extend  into  HL 

DCX 

H 

CCOCHAR:  MOV 

A  .M 

RET 

CCSX7:  MOV 

L  .  A 

RLC 

;  Test 

if  DE  > 

HL  (unsigned) 

SBB 

A 

CCUGT : 

XCHG 

MOV 

H  .A 

CALL 

CCUCMP 

RET 

RC 

;Fetch  a  full  16-bit  integer  from  the  address  in  HL 

DCX 

H 

::::nt:  mov 

A  ,  M 

RET 

:nx 

H 

MOV 

H  ,M 

;  Test 

if  DE  < 

HL  (unsigned) 

MOV 

L  ,  A 

CCULE  : 

CALL 

CCUCMP 

RET 

RZ 

; Stc^e  a  single 

byte  from 

HL  at  the  address  in  DE 

RC 

TCPCHAR:  MOV 

A  ,  L 

DCX 

H 

STAX 

D 

RET 

RET 

;Otc re  a  Ifc-bit 

integer  in 

HL  at  the  address  in  DE 

•.Common  routine  to  perform  unsigned  compare 

c:pint:  MCV 

A  .L 

; c  ar  r  y 

set  if 

DE  <  HL 

STAX 

D 

; zero/nonzero 

set  accordingly 

I  NX 

D 

CCUCMP 

:  MOV 

A  .  D 

MOV 

A  ,  H 

CMP 

H 

STAX 

D 

JNZ 

$*5 

RET 

MOV 

A  ,  E 

; Inclusive  "or" 

HL  and  DE 

into  HL 

CMP 

L 

CCOR:  MOV 

A  .  L 

LX  I 

H  .  1 

CfiA 

E 

RET 

MOV 

L  .A 

MOV 

A  .H 

; Shi  ft 

DE  arithmetically  right  by  HL  and  return 

ORA 

D 

CCASR : 

XCHG 

MOV 

H  .A 

MOV 

A  .  H 

RET 

RAL 

.•Exclusive  "or" 

HL  and  DE 

into  HL 

MOV 

A  ,  H 

•.Test  if  DE  > 
CCUGE:  CALL 

RNC 
DCX 
RET 

•Test  if  DE  < 
CCULT :  CALL 


HL  (unsigned) 
CCUCMP 


HL  (unsigned) 
CCUCMP 


<  HL) 
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MOV  H  ,  A 

MOV  A  ,  L 

RAR 

MOV  L  ,  A 

DCR  E 

JNZ  C  CA  SR ♦  1 

RET 

{Shift  DE  arithmetically  left  by  HL  and  return  in  HL 
CCASL:  XCHG 

DAD  H 

DCR  E 

JNZ  CCASL+ 1 

RET 

;Subtract  HL  from  DE  and  return  in  HL 
CCSUB:  MOV  A.E 

SUB  L 

MOV  L  ,  A 

MOV  A.D 

SBB  H 

MOV  H  ,  A 

RET 

;Form  the  two's  complement  of  HL 
emh  : 

CCNEG:  CALL  CCCOM 

I  NX  H 

RET 

;Form  the  one's  complement  of  HL 
CCCOM:  MOV  A.H 

CMA 

MOV  H  .  A 

MOV  A  ,  L 

CMA 

MOV  L  ,  A 


{Multiply  DE  by  HL  and  return  in  HL 
CCMULT:  MOV  B.H 

MOV  C.L 

LX  I  H.O 

CCMULT  1  :  MOV  A , C 

RRC 

JNC  $  ♦  4 

DAD  D 

X  R  A  A 

MOV  A.B 

RAR 

MOV  B  .  A 

MOV  A.C 

RAR 

MOV  C  ,  A 

ORA  B 

RZ 

X  R  A  A 

MOV  A.E 

R  AL 

MOV  E  .  A 

MOV  A.D 

RAL 

MOV  D  ,  A 

ORA  E 

RZ 

JMP  CCMULT1 

{Divide  DE  by  HL  and  return  quotient  in  HL.  remainder  in  DE 
CCDIV:  MOV  B.H 

MOV  C.L 

MOV  A.D 

X  R  A  B 

PUSH  PSW 

MOV  A.D 

ORA  A 

CM  CCDENEG 

MOV  A.B 

ORA  A 

CM  CCBCNEG 

M  V  I  A. 16 

PUSH  PSW 

XCHG 

LXI  D  ,  0 

CCDIV1:  DAD  H 

CALL  CCR  DEL 

JZ  CCDIV? 

CALL  CCCMPBCDE 

JM  CCDIV2 

MOV  A , L 

0  R I  1 

MOV  L , A 

MOV  A.E 

SUB  C 

MOV  E.A 

MOV  A.D 

SBB  B 

MOV  D  ,  A 

CCDIV? :  POP  PSW 

DCR  A 

JZ  C  CD  I V  3 

PUSH  PSW 

JMP  CCDIV1 

CCDIV3:  POP  PSW 

R  P 

CALL  CCDENEG 

XCHG 

CALL  CCDENEG 

XCHG 

RET 

CCDENEG:  MOV  A.D 
CMA 

MOV  D  .  A 

MOV  A.E 

CMA 

MOV  E.A 

I  NX  D 


CCBCNEG:  MOV  A.B 

CMA 

MOV  B  ,  A 


MOV  A.C 

CMA 

MOV  C.A 

I  NX  B 

RET 

CCRDEL:  MOV  A.E 

RAL 

MOV  E.A 

MOV  A.D 

RAL 

MOV  D.A 

ORA  E 

RET 

CCCMPBCDE:  MOV  A.E 
SUB  C 

MOV  A.D 

SBB  B 

RET 

(endasm 


Oasm 

;  library  for  small-C  --  Part  II 

;  Source:  lib2 
;  Version:  September  3,  1982 

;  Adapted  from:  CCC.ASM  (C.CCC).  BDS  C  version  l.«5.  11/22/81 

;  Original  written  by  Leor  Zolman 
;  Modification  by  Edward  K.  Ream 


base  : 

equ 

0  ; 

start  of  r 

•am  in  system 

bdos : 

equ 

base*5 

t pa  : 

equ 

ba  se+ 1 OOh 

f  cb : 

e  qu 

base+5ch 

nfebs  : 

equ 

8  { 

maximum  II 

of  files  open  at  one  time 

tbuf  f : 

equ 

base+80h 

origin: 

equ 

t  pa 

exitad  : 

equ 

base  { 

warm  boot 

location 

define  ASCII  codes; 


cr:  equ  Odh  {carriage  return 

If:  equ  Oah  {linefeed 

newlin:  equ  If  {newline 

tab:  equ  9  ;tab 

bs:  equ  08h  {backspace 

cntrlc:  equ  3  ;control-C 


define  BDOS  call  codes: 


errorv  equ  255 

con  i n  :  equ  1 
conout  :  equ  2 
1  stout  :  equ  5 
dconio :  equ  6 
pstrng:  equ  9 
getl  in  :  equ  10 
cstat :  equ  1  1 

select :  equ  1  *1 
openc  :  equ  15 
closec  :  equ  16 
dele  :  equ  19 

reads:  equ  20 

writs:  equ  21 

create:  equ  22 
renc:  equ  23 

sdma:  equ  26 

readr :  equ  33 

writr:  equ  34 

efsize:  equ  35 
sr recc  :  equ  36 

;  Define  global  varialbes  used  by  the  library 


args  : 

d  s 

1  4 

{"arghak"  puts  args  here. 

arg  1 

e  qu 

args 

arg2 

equ 

args+2 

a  r  g  3 

e  qu 

args+4 

a  r  g  4 

equ 

arg  s*  6 

arg5 

equ 

args+8 

a  rg6 

equ 

a  rg  s+  1  0 

arg7 

e  qu 

a  rg  s-*- 1  2 

iohac  k  : 

d  s 

6 

{room  for  I/O  subroutines  for  use 
;by  "  i  n  p  "  and  *'outp''  library  routines 
{(initialized  by  init) 

r  seed 

d  s 

8 

{seed  for  random  number  routines 
{(initialized  by  init) 

tmp : 

d  s 

1 

;  misc.  garbage  space 

tmp  1  : 

ds 

2 

tmp2 : 

d  s 

2 

tmp2a  : 

d  s 

2 

ungetl  : 

d  s 

1 

{where  characters  are  "ungotten" 

lastc  : 

d  s 

1 

{last  char  typed 

al loop : 

d  s 

2 

{storage  allocation  pointers 

a  1 ocmx  : 

d  s 

2 

{(initialized  by  init) 

(Continued  on  next  page) 


•.error  value  from  BDOS 

;get  a  character  from  console 
{write  a  character  to  console 
{write  a  character  to  list  device 
{direct  console  I/O  (only  for  CP/M  2.0) 
{print  string  (terminated  by  '$') 

;get  buffered  line  from  console 

;get  console  status 

•.select  disk 

{open  a  fi  le 

{close  a  fi le 

{delete  a  file 

{read  a  sector  (sequential) 

{write  a  sector  (sequential) 

{make  a  file 
{rename  file 
{set  dma 

{read  random  sector 
{write  random  sector 
{compute  file  size 
; set  random  record 
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(Listing  continued,  text  begins  on  page  62) 

;  The  fcb  table  (fcbt):  36  bytes  per  file  control  block 

fcbt:  d  s 

36«nfcbs 

;reserve  room  for  fob's 

;  The  fd  table:  one  byte  per  file  specifying  r/w/open  as  follows 

;  bit 

0  is  high 

if  open  , 

low  if  closed 

;  bit 

1  is  high 

if  open 

for  read 

:  bit 

2  is  high 

if  open 

for  write 

:  »  both  bi 

and  b2  may 

be  high) 

f  dt :  d  s 

n  fc  bs 

;one  byte  per  fcb 

:  The  command  line  is 

copied  here  by  init: 

com  1 i n :  d  s 

131 

;  c  opy 

of  the  command  line 

;  This  is  where  "init 

’  places 

the  array  of  argument  pointers: 

;  the  "argv 

’  parameter  points 

2  bytes  before  arglst. 

;  thus,  up 

to  30  parameters  may  be  passed  to  main(). 

arglst:  ds 

60 

;  Because  small-C  pushes  arguments  in  the  order  in  which 

;  they  appear  in  a  program,  it 

is  not  possible  to  know  where 

;  the  first 

ar gumen  t 

is  unless 

the  number  of  arguments  is 

;  known. 

;  The  following  three 

routines 

move  arguments  from  the 

;  stack  into  the  argument  area 

,  depending  on  the  number 

;  of  arguments  to  the 

function 

get  3args : 

lxi 

h 

; point  at  arg  3 

dad 

sp 

push 

h 

;get  it 

mov 

a  ,m 

inx 

h 

mov 

h  ,m 

mov 

1  ,  a 

shld 

a  r  g  3 

pop 

h 

inx 

h 

;point  at  arg  2 

inx 

h 

Jmp 

get2next 

ge  t  2a  r g  s  : 

lxi 

h 

;point  at  arg  2 

dad 

sp 

get2r.ext : 

push 

h 

mov 

a  ,m 

;get  arg  2  from  stack 

inx 

h 

mov 

h  ,m 

mov 

1  .  a 

shld 

arg2 

;store  it 

pop 

h 

inx 

h 

inx 

h 

jmp 

get Inex  t 

get  'arg  : 

lxi 

h 

; point  at  arg  1 

dad 

sp 

get  1 nex  t : 

mov 

a  ,m 

;get  arg  1  from  stack 

inx 

h 

mov 

h  ,m 

mov 

1  ,  a 

shld 

arg  1 

•.store  it 

ret 

;  These  routines  get 

the  indicated  parameter  into  both 

;  the  a  and 

hi  r e  g  s  , 

assuming 

that  the  correct  call  to 

;  either  getlarg,  get2args  or 

get3args  has  been  made. 

m  a  1 1  o  h  : 

1  hi  d 

arg  1 

mov 

a  ,  1 

re  t 

m  a  2 1  o  h  : 

1  hid 

a  rg2 

mov 

a  ,  1 

ret 

ma  3toh : 

lhld 

arg3 

mov 

a  ,  1 

re  t 

;  This  routine  is  called  first 

to  do  argc  &  argv  processing 

;  and  some 

odds  and  ends  initializations: 

-  push  argc  and  argv  in  reverse  order  from  BDS  C  - 


ccgo : 

init:  pop  h  ;store  return  address 

shld  tmp2  ;  somewhere  safe  for  the  time  being 

; -  push  later  - 

;  1 xi  h  ,arglst-2  ;set  the  "argv"  that  the 

;  push  h  ;  main  program  will  get. 


Initialize  storage  allocation  pointers: 

-  you  can  add  these  if  you  modify  the  small-C  compiler  - 

-  so  that  it  defines  the  label  freram  to  point  after  the  - 

-  end  of  the  externals  - 

lxi  h, freram  ;get  address  after  end  of  externals 

shld  allocp  ;store  at  allocation  pointer  for  sbrk(  ) 
lxi  h,1000  ;default  safety  space  between  stack  and 

shld  alocmx  ;  highest  allocatable  address  in  memory 

;  ( for  use  by  "  sbr k" . ) . 


Initialize  random  seed: 


lxi 

h  ,59dch 

let's 

stick  something  wierd  into  the 

shld 

r  seed 

first 

16  bits  of 

the  random-number  seed 

initialize  I/O 

hack  locations 

mv  i 

a  , Od  bh 

; " in"  op. 

for  "in  xx;  ret" 

s  ta 

i ohack 

mvi 

a  , Od 3h 

j "out"  op 

for  "out  xx;  ret" 

s  ta 

i ohack* 3 

mvi 

a  ,0c9h 

;''ret"  for 

above  subroutines 

sta 

i  ohack  +  2 

;the  port 

number  is  filled  in 

s  ta 

i ohack*5 

;  b  y  "  i  n  p  " 

and  "outp" 

mv  i 

c  ,  1  1 

;interrogate  console  status  to  see  if 

call 

bdo  s 

;there  is  a  stray  character. 

ora 

a 

;used  to  be  ' ani  1'...  better  for 

nop 

;for  some  CP/M  like  systems 

Jz 

i ni tzz 

mvi 

c  ,  1 

;if  input  present,  clear  it 

call 

bdos 

i ni tzz 

lxi 

h  ,tbuf f 

;  i f  arguments  given,  process  them 

lxi 

d  , coml  i n 

;get  ready  to  copy  command  line 

mov 

b  ,m 

;first  get  length  of  it 

inx 

h 

mov 

a  ,b 

ora 

a 

if  no  arguments,  don't  parse  for  argv 

Jnz 

i  ni  tl 

lxi 

d  ,  1 

set  argc  to  1  in  such  a  case. 

Jmp 

i5 

ini tl : 

mov 

a  ,m 

ok,  there  are  arguments,  parse... 

stax 

d 

first  copy  command  line  to  comlin 

i  nx 

h 

inx 

d 

der 

b 

jnz 

i  ni  tl 

x  ra 

a 

place  zero  following  line 

s  ta  x 

d 

lxi 

h  ,coml in 

;now  compute  pointers  to  each  arg 

lxi 

d  ,  1 

;arg  count 

lxi 

b  .arglst 

;where  pointers  will  all  go 

x  ra 

a 

;clear  "in  a  string"  flag 

s  ta 

t  mp  1 

i  2 : 

mov 

a  ,m 

between  ar gs . . . 

i  nx 

h 

cpi 

'  ' 

Jz 

i  2 

ora 

a 

Jz 

i  5 

if  null  byte,  done  with  list 

cpi 

i  n  i 

Jnz 

i  2a 

q  uote? 

sta 

tmp  1 

yes.  set  "in  a  string"  flag 

Jmp 

i  2b 

i  2a  : 

d  cx 

h 

i  2b : 

mov 

a  .1 

ok,  HL  is  a  pointer  to  the  start 

stax 

b 

of  an  arg  string,  store  it. 

i  nx 

b 

mov 

a  ,h 

stax 

b 

inx 

b 

inx 

d 

bump  arg  count 

i  3: 

mov 

a  ,m 

inx 

h 

pass  over  text  of  this  arg 

ora 

a 

if  at  end ,  all  done 

Jz 

15 

push 

b 

if  tmpl  set,  in  a  string 

mov 

b  ,  a 

(so  we  have  to  ignore  spaces) 

Ida 

t  mp  1 

ora 

a 

mov 

a  ,b 

pop 

b 

jz 

i  3a 

cpi 

t  » . 

we  are  in  a  string. 

jnz 

13 

check  for  terminating  quote 

x  ra 

a 

if  found,  reset  "in  string"  flag 

sta 

tmp  1 

d  cx 

h 

mov 

m ,  a 

and  stick  a  zero  byte  after  the  string 

i  nx 

h 

and  go  on  to  next  arg 

i  3a  : 

c  pi 

'  ' 

now  find  the  space  between  args 

jnz 

13 

dcx 

h 

found  it.  stick  in  a  zero  byte 

mvi 

m  .  0 

inx 

h 

jmp 

i  2 

and  go  on  to  next  arg 

90 
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i5:  push  d  ; a  1 1  done  finding  args.  Set  argc . 

lxi  h.arglst-2  ; -  now  push  argv  - 

push  h 

mvi  b.nfcbs  ;now  initialize  all  the  file  info 

lxi  h.fdt  ; ( just  zero  the  fd  table) 

i6 :  m vi  m  ,  0 

i  nx  h 

dcr  b 

jnz  16 

x  ra  a 

sta  ungetl  ;clear  the  push-back  byte 

sta  lastc  ;and  last  character  byte 

lhld  tmp2 

pchl  ;all  done  Initializing. 

5  General  purpose  error  value  return  routine: 


error  : 

lxi 

h  ,  - 1 

Igeneral  error  hand ler . . . j ust 

ret 

;returns  -  1  in  HL 

;  Here 

are  file 

I/O  handling  routines,  only  needed  under  CP/M: 

;  Close 

any  open  files 

and  reboot: 

qzex i t : 

exit: 

mvi 

a,7+nfcbs  ;start  with  largest  possible  fd 

exit!: 

push 

psw 

land  scan  all  fd's  for  open  files 

cal  1 

fgfd 

;is  file  whose  fd  is  in  A  open? 

jc 

exi  t2 

; i f  not,  go  on  to  next  fd 

m  ov 

1  ,  a 

;else  close  the  associated  file 

mvi 

h  .0 

push 

h 

call 

close 

pop 

h 

ex  it2: 

pop 

p  sw 

d  cr 

a 

;and  go  on  to  next  one 

cpi 

7 

jnz 

exit  1 

jmp 

e  x i tad 

;done  closing;  now  reboot  CP/M 

;  Close 

the  file 

whose 

fd  is  1st  arg: 

qzclose  : 
close: 

call  getlarg  ; -  new  - 

call  setdma  ;library  function  just  jumps  here. 

call  maltoh  :get  fd  in  A 

call  fgfd  ;see  if  it  is  open 

Jc  error  ;if  not,  complain 

mov  a  , m 

ani  4 

Jz  close2  ;the  file  isn't  open  for  write 

push  h  ;save  fd  table  entry  addr 

call  maltoh  ; - was  ma2toh - move  argl  to  A 

push  b 

call  fgfcb  : get  the  appropriate  fcb  address 

xchg  ;put  it  in  DE 

mvi  c,l6  ;get  BDOS  function  #  for  close 

call  bdos  ;and  do  it! 

pop  b 

pop  h 

close2:  mvi  m.O  ;close  logically 

cpi  255  ; i f  255  comes  back,  we  got  problems 

lxi  h  .0 

rnz  ;return  0  if  OK 

dcx  h  ;return  -1  on  error 

ret 

;  Determine  status  of  file  whose  fd  is  in  A. ..if  the  file 
;  is  not  open,  return  C  flag  set,  else  clear  C  flag: 

f  g  fd :  call  setdma 

mov  d  ,  a 

s  ui  8 

re  ; i f  fd  <  8,  error 

cpi  n  fc  bs 

cmc  ;don't  allow  too  big  an  fd  either 

r  c 

push  d 

mov  e.a  ; OK ,  we  have  a  value  in  range.  Now 

mvi  d,0  ;  see  if  the  file  is  open  or  not 

lxi  h.fdt 

dad  d 

mov  a  ,m 

ani  1  ;bit  0  is  high  if  file  is  open 

s  tc 

pop  d 

mov  a  ,d 

rz  ;return  C  set  if  not  open 

ret  ;else  reset  C  and  return 


Set  up  a  CP/M  file  control  block  at  HL  with  the  file  whose 
simple  nu 1 1 -term i na ted  name  is  pointed  to  by  DE : 

Format  for  filename  must  be:  "[white  sp a c e ] [ d : ] f i 1 ename  .  e x t 


set  f  c  b : 

call  setdma  ;set  up  an  fcb  at  HL  for  filename  at  DE 
push  b 


call 

x  gwsp 

;ignore  blanks  and  tabs 

mvi 

b  .8 

push 

h 

i  nx 

d 

Ida  x 

d 

dcx 

d 

cpi 

'  : ' 

;default  disk  byte  value  is  0 

mvi 

a  ,0 

;  (for  currently  logged  disk) 

jnz 

set  f  1 

Idax 

d 

;oh  oh. ..we  have  a  disk  designator 

call 

mapuc 

;make  it  upper  case 

sui 

' 

; a  nd  fudge  it  a  bit 

i  nx 

d 

i  nx 

d 

set  f  1  : 

m  ov 

m  ,  a 

i  nx 

h 

call 

patchnm 

I  now  set  filename  and  pad  with  blanks 

ldax 

d 

c  pi 

'  .  ' 

land  if  an  extension  is  given. 

jnz 

s  et  f  c  b2 

i  nx 

d 

set  f cb2 

mvi 

b  .3 

;set  the  extension  and  pad  with  blanks 

call 

setnm 

x  ra 

a 

land  zero  the  appropriate  fields  of  the  fcb 

mov 

m  ,  a 

lxi 

d  ,20 

d  ad 

d 

mov 

m  ,  a 

i  nx 

h 

mov 

m  ,  a 

;zero  the  random  record  bytes 

i  nx 

h 

mov 

m  ,  a 

i  nx 

h 

mov 

m  ,  a 

pop 

d 

pop 

b 

ret 

patchnm 

cal  1 

setnm 

lanother  patch  from  "vsetfcb" 

jn>P 

setnn>3 

;  This 

routine 

copes  up 

to  B  characters  from  memory  at  DE  to 

;  memory  at  HL 

and  pads 

with  blanks  on  the  right: 

setnm  : 

push 

b 

setnm  1  : 

ldax 

d 

c  pi 

■  ■  • 

;wild  card? 

mvi 

a  , '  ?  ' 

;  i f  so,  pad  with  ?  characters 

j* 

pad  2 

setnm2 : 

ldax 

d 

call 

leg  fc 

;next  char  legal  filename  char? 

Jc 

pad 

;if  not,  go  pad  for  total  of  B  characters 

mov 

m  ,  a 

;else  store 

i  nx 

h 

i  nx 

d 

dcr 

b 

jnz 

setnm 1 

;and  go  for  more  if  B  not  yet  zero 

pop 

b 

setnm3  : 

ldax 

d 

;skip  rest  of  filename  if  B  chars  already  found 

cal  1 

leg  fc 

r  c 

i  nx 

d 

Jmp 

setnm3 

pad  : 

mvi 

a  , '  ' 

;pad  with  B  blanks 

pad2  : 

mov 

m  ,  a 

; pad  with  B  instances  of  char  in  A 

i  nx 

h 

dcr 

b 

jnz 

pad2 

pop 

b 

ret 

;  Test 

if  char 

in  A  is 

lega’  character  to  be  in  a  filename: 

legfc : 

cal  1 

mapuc 

c  pi 

'  .  ' 

;  is  illegal  in  a  filename  or  extension 

s  tc 

r  z 

cpi 

'  :  ' 

;  so  is  '  :  ' 

stc 

r  z 

c  pi 

7fh 

;delete  is  no  good 

stc 

r  z 

c  pi 

’  !  ' 

;if  less  than  exclamation  pt ,  not  legal  char 

ret 

;else  good  enough 

;  Map  character 

in  A  to 

upper  case  if  it  is  lower  case: 

mapuc  : 

cpi 

'  a ' 

r  c 

cpi 

'  z’*1 

r  nc 

sui 

32 

;if  lower  case,  map  to  upper 

ret 

Ignore  blanks  and  tabs  at  text  pointed  to  by  DE : 


(Continued  on  next  page) 
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(Listing  continued,  text  begins  on  page  62) 

igwsp:  dcx 

d 

i gwsp  1 :  i nx 

d 

ldax 

d 

cpi 

’  r 

Jz 

i gwsp 1 

cpi 

9 

Jz 

i gwsp  1 

ret 

;  This  routine  does  one 

of  two  things,  depending 

;  on  the  value  passed  in 

A  . 

;  If  A  is  zero ,  then  it 

finds  a  free  file  slot 

;  (if  possible),  else  returns  C  set. 

;  If  A  is  non 

-zero  ,  then 

it  returns  the  address 

;  of  the  fcb 

corresponding  to  an  open  file  whose 

;  fd  happens 

to  be  the  value  in  A,  or  C  set  if  there 

;  is  no  file 

associated 

with  f d . 

f  g  fcb :  push 

b 

call 

setdma 

ora 

a 

;look  for  free  slot? 

mov 

c  ,  a 

jnz 

f  gfc2 

; i f  not ,  go  away 

mvi 

b  ,  n  f  c  b  s 

;yes.  do  it... 

lxi 

d  .  f  dt 

lxi 

h  ,fcbt 

mvi 

c  .8 

fgfcl:  ldax 

d 

a  n  i 

1 

mov 

a  ,c 

jnz 

f gfc  1  a 

; f ound  free  slot? 

pop 

b 

; y es .  all  done . 

ret 

fgfcia:  push 

d 

lxi 

d  .  36 

;fcb  length  to  accommodate  random 

d  ad 

d 

pop 

d 

inx 

d 

inr 

c 

dcr 

b 

jnz 

fgfcl 

f  gfc 1 b :  stc 

pop  ’ 

b 

ret 

[return  C  if  no  more  free  slots 

fgfc2:  call 

f  gfd 

[compute  fcb  address  for  fd  in  A: 

Jc 

f  gfc  1  b 

[return  C  if  file  isn’t  open 

sui 

8 

mov 

1  ,  a 

[put  (fd-8)  in  HL 

mvi 

h  .0 

dad 

h 

[double  it 

dad 

h 

[  4  •  a 

mov 

d  ,  h 

[save  4*a  in  DE 

mov 

e  ,  1 

dad 

h 

;  8*a 

dad 

h 

;  1 6  •  a 

dad 

h 

;  32  •  a 

dad 

d 

;  36  •  a 

xchg 

[put  36*a  in  DE 

lxi 

h  ,f cbt 

[add  to  base  of  table 

dad 

d 

[result  in  HL 

mov 

a  ,c 

[and  return  original  fd  in  A 

pop 

b 

ret 

setdma :  push 

d 

[just  a  preventative  measure, 

push 

b 

[since  the  default  I/O  buffer 

push 

psw 

[tends  to  magically  change 

push 

h 

[around  by  itself  when  left 

mvi 

c  .26 

[in  CP/M's  hands  »! 

lxi 

d  ,  tbuf f 

cal  1 

bdos 

pop 

h 

pop 

p  sw 

pop 

b 

pop 

d 

ret 

lendasm 

•f  a  sr. 

:  File  I/I  library  for  small-C  —  Part  I 

;  Source:  fiolibl 
;  Version;  September  3,  1982 

;  Adapted  from  deff2.csm.  BDS  C  version  1.46,  3/22/82 

;  Original  by  Leor  Zolman 
;  Modifications  by  Edward  K.  Ream 


Functions  appearing  in  this  file: 


getchar 
s  et  f c  b 
uni  ink 
f  ab  or  t 


kbhi  t 
read 
seek 
f  cbaddr 


ungetch  putchar  putch 

write  open  close 

tell  rename 

exit  bdos  bios 


gets 

creat 


qzgetohar  : 
getchar  : 

Ida 

ora 

mov 

jz 

x  r  a 
s  ta 
m  v  i 
ret 


ungetl  ;any  character  pushed  back? 


1  ,  a 
g  ch2 
a 

ungetl 
h  ,0 


;yes.  return  it  and  clear  the  pushback 
; b  y te  in  C.CCC. 


gch2 : 


gch  3 : 


qzkbhi t  : 
kbhit : 


push 

b 

mvi 

c  .conin 

call 

bdos 

pop 

b 

cpi 

cntrlc 

jz 

base 

c  pi 

1  a  h 

lxi 

r  z 

h  ,  - 1 

mov 

1  ,  a 

cpi 

cr 

jnz 

gch3 

push 

b 

mvi 

c  .conout 

mvi 

e  .If 

call 

bdos 

pop 

b 

mv  i 

1 .newlin 

mvi 

ret 

h  ,0 

Ida 

ungetl 

mvi 

h  ,0 

mov 

1  •  a 

ora 

rnz 

a 

push 

b 

mvi 

c  ,  csta  t 

call 

bdos 

pop 

b 

ora 

a 

lxi 
r  z 

h  ,0 

i  nr 

1 

ret 


;control-C  ? 

; i f  so ,  reboot. 
;control-Z  ? 

; i f  so,  return  -1. 


[carriage  return? 


; i f  so,  also  echo  linefeed 


;and  return  newline  (linefeed).. 


;any  character  ungotten? 

; i f  so,  return  true 

;else  interrogate  console  status 

;0  returned  by  BDOS  if  no  character  ready 

[return  0  in  HL  if  no  character  ready 
[otherwise  return  1  in  HL 


qzungetch : 
ungetch : 

call  getlarg  ; — -  new  - 

Ida  ungetl 

mov  1  ,  a 

push  h 

call  maltoh  ; -  was  ma2toh  - 

sta  ungetl 

pop  h 

mvi  h,0 

ret 


[this 

is  a  new 

function 

qzputs 

puts  : 

call 

get  la  r g 

call 

maltoh 

push 

b 

call 

put  s  1 

pop 

b 

puts  1  : 

ret 

mov 

a  ,m 

cpi 

0 

r  z 

push 

h 

mov 

1  •  a 

push 

h 

call 

putchar 

pop 

h 

pop 

h 

inx 

h 

jmp 

puts  1 

;use  putchar1 s  interrupt  logic 


qzputchar : 
putchar : 

call  getlarg  ; -  new  - 

call  maltoh  ;get  character  in  A 

push  b 

mvi  c  .conout 

cpi  newlin  [newline? 

Jnz  putl  I  i  f  not,  just  go  put  out  the  character 

mvi  e  ,cr  ;else...put  out  CR-LF 

call  bdos 

mvi  c  .conout 

mvi  a  ,  1  f 


putl:  mov  e  , a 

call  bdos 


put2:  mvi 

call 
ora 

jnz 

pop 

ret 

put3:  mvi 

call 
c  pi 
jz 

pop 

ret 


c.cstat  ;now,  is  input  present  at  the  console? 

bdos 

a 

put  3 

b  ; n  o  .  . . a  1 1  done  . 


c  ,  con i n 
bdos 
c  nt  r 1 c 
base 
b 


yes.  sample  it  (this  will  always  echo  the 
character  to  the  screen,  alas) 
is  it  control-C? 
if  so,  abort  and  reboot 
else  ignore  it. 


qzputch  : 
putch  : 

call  getlarg  ; new  — — 

call  maltoh 
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push  b 

mvi  c  .conout 

mov  e  ,  a 

c  pi  newl i n 

jnz  putchl  ;if  not  newline,  just  put  it  out 

mvi  e  ,cr  ;else  put  out  CR-LF 

call  bdos 

mvi  c  .conout 

mvi  e  ,  1  f 

putchl:  call  bdos 

pop  b 

ret 


qzgets : 
gets  : 

call  getlarg  ; -  new  - 

call  maltoh  ;get  destination  address 

push  b  '.save  BC 

push  h 

push  h 

lxi  h,-l50  ;use  space  below  stack  Tor  reading  line 

dad  sp 

push  h  ;save  buffer  address 

mvi  m,88h  ;Allow  a  max  of  about  135  characters 

mvi  c  ,get  1  in 

xchg  ; put  buffer  addr  in  DE 

call  bdos  ;get  the  input  line 

mvi  c  .conout 

mvi  e.lf  ;put  out  a  LF 

call  bdos 

pop  h  ;get  back  buffer  address 

inx  h  ;polnt  to  returned  char  count 

mov  b ,m  ;set  B  equal  to  char  count 

inx  h  ; HL  points  to  first  char  of  line 

pop  d  ; DE  points  to  start  destination  area 

copyl:  mov  a  ,b  ;copy  line  to  start  of  buffer 

ora .  a 

Jz  get  s2 

mov  a  , m 

s  ta  x  d 

inx  h 

inx  d 

dcr  b 

Jmp  copyl 

gets2:  xra  a  ;store  terminating  null 

stax  d 

pop  h  [return  buffer  address  in  HL 

pop  b 

ret 


qzsetfcb : 

call  get  2args  ; was  arghak 

push  b 

lhld  arg2  :get  pointer  to  name  text 
i  gsp  :  mov  a  ,m 

inx  h 

cpi  1  1 

Jz  i gsp 

cpi  tab 

Jz  i gsp 

dcx  h 

xchg  ;set  DE  pointing  to  1st  non-space  char 

lhld  argl  [get  -->  fcb  area 

call  set  fcb  ;  do  it 

lxi  h  , 0  '.all  OK. 

pop  b 

ret 

qzread  : 
r ead  : 

call  get  3args  ; was  arghak 

Ida  argl 

call  fgfd 

Jc  error  [error  if  illegal  fd 

mov  a  ,m 

ani  2  [open  for  read? 

jz  error  [error  if  not 

push  b 

Ida  argl 

call  fgfcb 

shld  tmp2  ; t mp2  will  hold  dma  addr 

lxi  h,0  [count  of  I  of  successful  sectors  read 

shld  tmp2a  ;  will  be  kept  at  tmp2a 

read2:  lhld  arg3  [done? 

mov  a  ,h 

ora  1 

j  z  r  ea  dU 

read2a:  lhld  arg2  [else  read  another  sector 

xchg  [DE  is  dma  addr 

mvi  c  ,  sdma 

call  bdos  ;set  DMA 

lhld  tmp2 

xchg  ;DE  is  fcb  addr 

mvi  c  .reads 

push  d  [save  de  so  we  can  fudge  nr  field  if 

call  bdos  ;we  stop  reading  on  extent  boundary... 

pop  d  [  CP/M  sucks! 

c  pi  2 

pop  b 

jz  error  [if  error,  abort 

push  b 

cpi  1 

jnz  read6  [EOF? 


read  3 :  lxi  h,32  [yes.  are  we  on  extent  boundary? 

dad  d  ;if  so,  adjust  for  CP/M's  stupidity  here 

mov  a *m  ;by  turning  an  80h  sector  count  into  OOh. 

cpi  80h 

Jnz  readU 

mvi  m .  0  ;yes.  reset  nr  to  0... 

readU:  lhld  tmp2a 

read5c  pop  b 

ret 

read6:  lhld  arg3 

dcx  h 

shld  arg3 

lhld  a  r g2 

lxi  d  .  1 28 

dad  d 

shld  arg2 

lhld  tmp2a 

inx  h 

shld  tmp2a 

jmp  read2 


qzwr ite  : 
write  : 

call  get3args  [ -  was  arghak  - 

Ida  argl 

call  fgfd 

jc  error 

mov  a  ,m 

ani  d 

jz  error 

push  b 

Ida  argl 

call  fgfcb 

shld  t  mp2 

lxi  h.O 

shld  tmp2a 

lxi  d.tbuff  ;80  for  normal  CP/M,  else  d280 

mvi  c  , sdma 

call  bdos 

writl:  lhld  arg3  [done  yet? 

mov  a  ,h 

ora  1 

lhld  tmp2a  ;if  so,  return  count 

Jz  w r i  1 3 

lhld  arg2  [else  copy  next  128  bytes  down  to  tbuff 

lxi  d.tbuff  [80  for  normal  CP/M,  else  d280 

mvi  b  ,  1 28 

writ2:  mov  a,m 

stax  d 

inx  h 

inx  d 

dcr  b 

jnz  writ2 

shld  arg2  [save  ->  to  next  128  bytes 

lhld  tmp2  [get  addr  of  fcb 

xchg 

mvi  c, writs  [go  write 

call  bdos 

ora  a  [error? 

lhld  tmp2a  [if  so.  return  9  of  successfully  written 
jnz  writ3  [  sectors. 

inx  h  [  else  bump  successful  sector  count, 

shld  tmp2a 

lhld  arg3  ;  debump  countdown, 

dcx  h 

shld  arg3 

Jmp  writl  ;  and  go  try  next  sector 

writ3:  pop  b 

ret 


q zope n  : 
open  : 

call  get2args  ; -  was  arghak  - 

xra  a 

call  fgfcb  [any  fcb's  free? 

jc  error  ;if  not,  error 

sta  tmp 

xchg 

lhld  argl 

xchg 

push  b 

call  setfcb 

mvi  c  .openc 

call  bdos 

cpi  errorv  [successful  open? 

pop  b 

jz  error  [if  not,  error 

Ida  tmp 

call  fgfd  [get  HL  pointing  to  fd  table  entry 

Ida  arg2 

ora  a  [open  for  read? 

mvi  d  ,  3 

J  z  o  pe  n  1 

dcr  a 

mvi  d  , 5 

jz  openl  [write? 

dcr  a 

jnz  error  [else  must  be  both  or  bad  mode, 

mvi  d  ,7 

openl:  mov  m  ,d 

Ida  tmp 

mov  1 , a 

mvi  h  ,0 

ret 


qzcreat  : 
creat  : 

call  getlarg  ; -  was  arghak  - 

lhld  argl 

push  b  (Continued  on  next  page) 
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RED  -  Listing 

(Listing  continued,  text  begins  on  page  62) 


push 
call 
pop 
mv  i 
1  x  i 
call 
c  pi 
pop 
Jz 

lhld 

push 

lxi 

push 

call 

pop 

pop 


q  zun 1 i nk  : 
unlink: 


q zseek  : 
seek: 


qzte  1  i  : 
tell: 


unlink  -.erase  any  old  versions  of  file 
d 

c .create 
d  .  feb 
bdo  s 
e  rr  or  v 


argl  ; -  push  these  in  reverse  order 

h 

h,2  ;open  for  read/write 

h 


call 

call 

push 

xchg 

lxi 

call 

m  vi 

call 

1  xi 


call 
1  da 
call 
jc 

push 

push 


get  1  a  r  g 
ma  1  toh 


h  ,f  cb 
s  e  t  f  c  b 
c  .dele 
bdo  s 
h  ,0 


get3args 
arg  1 
fgfeb 
error 


; - was  arghak - 


;error  if  file  not  open 
;save  feb  address 


push 
lxi 
dad 
mov 
lxi 
d  ad 
mov 
x  ra 


m  vi 
r  ar 
mov 
add 


a  na 
jP 
1  nr 

te 1 1 2  :  pop 
ret 


qzrename  : 
rename : 


call 

push 

lhld 

xchg 

lxi 

cal  1 

lhld 

xchg 

lxi 

call 

lxi 


call 

jc 


get  ’arg 
ma  1 1  oh 
fgfeb 
error 


; - new - 

{get  fd  value 


b  ,m 
d  .20 


;  put  extent  t  in  B 


;  put  sector  t  i  n  C 

{rotate  extent  right  one  bit 

;old  bO  — >  Carry 


-.rotated  value  becomes  high  byte  of 

;tell  position 

{rotate  bO  of  extent  into  A 

;save  rotated  extent  number  in  B 
;add  rotated  extent  number  to  sector 
;and  result  becomes  low  byte  of 
;tel 1  position 

;  i  f  both  rotated  extent  #  and  sector 
-.has  bit  7  hi. 

;then  the  sum  had  an  overflow,  so... 

;bump  position  number  by  256 
;  a  nd  all  done . 


get2args 

b 

arg  1 

h  ,wfcb 
set  f  cb 
arg2 

h  ,wfcb+  16 
set  feb 
d  , wf cb 


; - was  arghak - 


mvi 

c  , renc 

lhld 

push 

argl 

h 

cal  1 

bdos 

call 

tell 

;get  r/w  pointer  position  for  the  file 

pop 

b 

pop 

d 

cpi 

e  rr or  v 

jz 

e  rr  or 

xchg 

;put  present  pos  in  DE 

lxi 

h  .0 

Ida 

a  r  g  3 

ret 

lhld 

a  r  g2 

;get  offset  in  HL 

wf  cb : 

ds  53 

ora 

a 

;absolute  offset? 

Jz 

seek2 

;if  so,  offset  is  new  position 

d  ad 

d 

;else  add  offset  to  current  position 

qzf  abort : 

m  ov 

a  ,  1 

;convert  to  extent  and  sector  values 

i abort  : 

cal  1 

get  1  a  r g 

r  lc 

call 

ma 1 toh 

mov 

a  ,h 

call 

fgfd 

r  al 

Jc 

e  rr  or 

a  ni 

7  f  h 

mvi 

m  ,  0 

s  ta 

t  mp 

lxi 

h  .0 

xthl 

ret 

lxi 

d  .  12 

push 

h 

dad 

d 

qzf  ebaddr : 

emp 

m 

;jumping  over  extent  boundary? 

f  ebaddr 

jz 

s  ee  k  5 

cal  1 

get  1  a  r g 

xthl 

;  yes  . 

call 

ma 1 toh 

xchg 

call 

fgfd 

m  vi 

c  .closec 

{close  old  extent 

Jc 

error 

push 

d 

call 

ma 1 toh 

call 

bdos 

call 

fgfeb 

pop 

d 

ret 

pop 

h 

cpi 

e  rr  or  v 

j  r.  z 

s  ee  k  U 

bdos 

equ 

5 

pop 

d 

qzbdos : 

pop 

b 

call 

get2args 

Jmp 

error 

push 

b 

Ida 

argl 

Ida 

t  mp 

mov 

c  ,  a 

mov 

n ,  a 

lhld 

a  r  g2 

push 

d 

xchg 

mvi 

c .openc 

;  a  nd  open  new  one . 

cal  1 

bdos 

:al  1 

bdos 

pop 

b 

pop 

d 

ret 

cpi 

e  rr  or  v 

Jz 

seek3 

lxi 

h.32 

;and  set  nr  field 

qzbios : 

d  ad 

d 

bios: 

pop 

d 

call 

get  2a  r gs 

no  v 

a  ,  e 

push 

b 

a  r.  1 

T  h 

lhld 

base*  1 

n  sv 

m  ,  a 

dex 

h 

xchg 

{return  new  sector  8  in  HL 

dex 

h 

pop 

b 

dex 

h 

ret 

Ida 

argl 

mov 

b  ,  a 

add 

a 

-.clear  entry  in  fd  table 


; - was  arghak 

;get  C  value 

;get  DE  value 

;put  in  DE 

;make  the  bdos  call 

;and  return  to  caller 


; - was  arghak 


;get  addr  of  jump  table  ♦  3 
;set  to  addr  of  first  Jump 


;get  function  number  (1-85) 
;multiply  by  3 
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add 

b 

mov 

e  ,  a 

put 

in  DE 

m  v  i 

d  ,0 

dad 

d 

add 

to  base  of  jump  table 

push 

h 

a  nd 

save  for  later 

1  hi  d 

a  rg2 

get 

value  to  be  put  in  BC 

mov 

b  ,  h 

a  nd 

put  it  there 

mov 

c  ,  1 

1  x  i 

h  .retadd 

;where  call  to  bios  will  return  to 

x  th  1 

get 

address  of  vector  in  HL 

pch  1 

and 

go  to  it... 

retadd :  mov 

1  ,  a 

all 

done,  now  put  return  value  in  HL 

mvi 

h  .0 

pop 

b 

ret 

a  nd 

return  to  caller 

Hendasm 

0  a  am 

;  Extra  small-C  run  time  library 


Source  :  x  li  b 

Version:  August  29.  1982 

Adapted  from  deff2a.csm.  BDS  C  version  1-^6,  3/22/82 

Original  by  Leor  Zolman 
Modified  by  Edward  K.  Ream 


qzset jmp  : 

call  getlarg  ; -  new  - 

call  ma 1 toh 

mov  m,c  ;save  BC  (not  really  needed  in  small-C) 

i  nx  h 

mov  m,b 

i  nx  h 

xchg  ; sa ve  SP 

1 xi  h  ,0 

dad  sp 

xchg 

mov  m  ,  e 

i  nx  h 

mov  m  ,  d 

i  nx  h 

pop  d  ;save  return  address 

push  d 

mov  m  ,  e 

i  nx  h 

mov  m  ,  d 


1  xi 
ret 

h  .0 

and  return  0 

; long jmp( buffer 

,  return_ 

value) 

;  unlike 

the  BDS  C 

version  of  this  routine. 

;  the  return  value 

is  REQUIRED 

qzlongjmp: 

call 

get  2a  r  g  s 

; - new - 

call 

ma 1 toh 

;get  buffer  address 

mov 

c  .m 

restore  BC 

i  nx 

h 

mov 

b  ,m 

i  nx 

h 

mov 

e  ,m 

;restore  SP. ..first  put  it  in  DE 

i  nx 

h 

mov 

d  ,  m 

i  nx 

h 

shl  d 

temp 

;save  pointer  to  return  address 

call 

ma2toh 

;get  return  value 

xchg 

;put  return  val  in  DE,  old  SP  in  HL 

sphl 

;restore  SP  with  old  value 

pop 

h 

;  pop  return  address  off  stack 

lhld 

temp 

:get  back  ptr  to  return  address 

mov 

a  ,m 

i  nx 

h 

mov 

h  ,m 

mov 

1  .  a 

HL  holds  new  return  address 

xchg 

;ret  addr  in  DE,  return  value  in  HL 

push 

d 

;push  return  address  on  stack 

ret 

temp  :  d s  2 

II  end  asm 

;and  return . . . 

End  Listing  Two 
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CP/M  EXCHANGE 


by  Robert  Blum 


A  lot  of  space  has  been  devoted  to 
discussing  CP/M  Plus’s  new  architecture 
and  how  it  should  improve  program  exe¬ 
cution  speed  relative  to  I/O  operations. 
Until  recently  it  was  all  speculation,  but 
benchmark  comparisons  are  now  becom¬ 
ing  available  [see  this  month’s  Clinic,  page 
10] .  Most  of  the  reports  I  have  seen  point 
out  that  some  improvement  can  be  expect¬ 
ed  straight  out  of  the  box.  I  think  the  real 
story  will  begin  to  unfold  as  it  gains  more 
extensive  use  in  the  hacker  community. 

Quickening  the  Pace 

Carl  Bochert  of  San  Jose,  California 
called  me  several  weeks  ago  to  share  his 
experiences  with  CP/M  Plus.  His  system 
is  configured  with  256K  of  memory  to 
allow  plenty  of  work  space  for  directory 
hash  tables  and  disk  buffers.  To  bench¬ 
mark  his  system,  Carl  used  RMAC,  DR’s 
relocating  assembler,  to  assemble  several 
sample  programs.  He  experienced  approx¬ 
imately  a  17%  reduction  in  runtime  with 
the  standard  CP/M  Plus  system. 

Carl  also  indicated  that  he  made  a 
few  patches  which  produced  even  better 


results,  but  for  the  moment  will  reserve 
comment  on  their  content. 

CP/M  Plus  Memory  Management 

Last  month  I  reviewed  two  memory 
management  techniques  that  can  be  used 
to  expand  system  memory  beyond  the 
normal  64K  address  space  limitation  of 
most  8-bit  processors.  In  studying  the 
following  CP/M  Plus  memory  models  I 
think  it  will  become  more  clear  to  you 
how  all  the  pieces  fit  together. 

To  fully  implement  CP/M  Plus  re¬ 
quires  at  least  96K  of  memory  divided 
into  two  switchable  banks  and  one  fixed 
segment.  However,  a  typical  system  will 
probably  go  well  beyond  the  minimum  to 
at  least  160K  divided  into  three  48K 
switchable  banks  and  one  fixed  16K  seg¬ 
ment.  I  use  48K  for  the  switchable  area 
because  most  memory  boards  produced 
today  have  facilities  that  work  properly 
with  MP/M,  which  requires  this  segment 
size. 

Examining  a  banked  CP/M  Plus  mem¬ 
ory  model,  Figure  1  (below),  reveals  the 
complexities  that  are  faced  when  bringing 


the  system  up.  The  top  portion  of  mem¬ 
ory  is  called  “common  memory,”  which 
is  always  enabled  and  addressable.  The 
operating  system  is  divided  into  two 
modules:  the  resident  portion,  which 
resides  in  common  memory,  and  the 
banked  portion,  which  resides  just  below 
common  memory  in  bank  0.  All  remain¬ 
ing  memory  in  bank  0  is  split  for  use  by 
directory  hash  tables  and  data  buffers.  It 
is  not  a  requirement  for  bank  0  to  begin 
at  location  0.  When  the  system  is  com¬ 
bined  with  the  system  generation  utility, 
GENCPM,  starting  addresses  can  be 
entered  for  each  of  the  operating  system 
modules  and  data  storage  tables. 

Bank  1  is  the  transient  program  bank 
and  must  begin  at  location  0.  All  memory 
within  bank  1  must  be  contiguous  to  the 
top  of  banked  memory.  Since  most  of  the 
operating  system  is  in  a  bank  of  memory 
dedicated  to  operating  system  use,  it  is 
entirely  possible  to  achieve  a  TPA  size  of 
62K  —  quite  an  increase  over  56K,  which 
has  come  to  be  the  standard  for  CP/M 
2.2. 

Any  remaining  banked  memory  will 
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be  used  by  CP/M  Plus  to  maintain  a  cache 
of  deblocking  buffers  and  directory  rec¬ 
ords.  Avery  efficient  Least  Recently  Used 
(LRU)  buffering  scheme  is  employed  to 
manage  these  buffer  pools.  When  buffer 
space  is  exhausted,  the  buffer  that  is  least 
used  is  overwritten  by  incoming  data  and 
retrieved  again  later  as  needed. 

The  memory  model  for  a  nonbanked 
CP/M  Plus,  Figure  2  (page  98),  is  prac¬ 
tically  identical  to  CP/M  2.2  with  the 
exception  that  at  least  an  additional  2K 
will  be  used  by  the  operating  system.  The 
resulting  TPA  of  approximately  54K  may 
be  too  j;mall  for  some  applications  and 
must  be  seriously  considered. 

Setting  Sail  by  the  North  Star 

Ed  McMurray  of  Columbia,  South 
Carolina  recently  wrote  asking  some  ques¬ 
tions  about  Lifeboat’s  implementation  of 
CP/M  2.2  for  the  North  Star  computer. 
His  letter  brought  back  a  flood  of  fond 
memories.  More  years  ago  than  I  care  to 
mention,  I  had  finally  convinced  myself 
that  I  just  had  to  have  a  floppy  disk  sys¬ 
tem  to  replace  my  TDL  cassette  tape 
interface.  At  that  time  only  a  few  disk 
systems  were  available  for  the  S-100  bus; 
and  after  looking  around  for  the  best 
price,  I  put  down  what  seemed  to  be  a 
small  fortune  to  take  home  a  North  Star 
single -density  controller  board  and  a  sin¬ 
gle  Shugart  SA400  disk  drive.  Obviously, 
everything  was  in  kit  form.  After  correct¬ 
ing  a  few  solder  bridges  and  establishing  a 
suitable  software  interface  to  my  I/O 
boards,  I  was  on  the  air  in  grand  style.  My 
appetite  had  been  whetted ;  soon  one  drive 
grew  to  two;  double- density  controller 
boards  became  available,  and  obviously  1 
had  to  have  one.  For  some  unknown  rea¬ 
son,  I  still  didn’t  have  enough  storage.  I 
couldn’t  have  been  happier  when  the  UPS 
man  brought  my  new  8 -inch  drives  and 
controller.  And  now  I  keep  hearing  about 
these  things  called  hard  disks.  Let’s  see  — 
what  excuse  can  I  use  to  justify  that  new 
40Meg  drive? 

Ed’s  question  had  to  do  with  con¬ 
necting  different  manufacturers’  disk 
drives  to  the  same  controller  and  training 
the  BIOS  to  step  each  one  at  a  different 
rate.  To  insure  that  I  had  up-to-date  in¬ 
formation  I  made  a  call  to  Lifeboat  to  get 
their  guidance.  I  was  told  that,  in  release 
2.23 A  of  their  CP/M,  a  utility  program, 
SETCPM,  must  be  used  to  set  the  opera¬ 
tional  characteristics  for  each  drive.  The 
options  that  can  be  selected  are  fast  or 
slow  stepping  rates  and  whether  the  drive 
is  capable  of  single-  or  double-sided 
operation.  In  all  cases  double-density 
recording  is  assumed. 

One  alternative  solution  is  to  use  the 
public  domain  North  Star  BIOS  contained 
on  volume  82  available  from  CPMUG.  A 
brief  review  of  the  documentation  for 
this  program  specifically  points  out  that 
drives  with  differing  capabilities  (step 
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rates,  number  of  tracks,  etc.)  can  be  used 
on  the  same  system. 

Another  Byte  for  Apple 

The  CP/M  Users  Group  (CPMUG)  is 
now  offering  their  extensive  library  of 
public  domain  software  in  Apple  CP/M 
disk  format.  This  brings  to  three  the  num¬ 
ber  of  formats  they  offer.  They  can  be 
reached  at:  CPMUG,  The  CP/M  Users 
Group,  1651  Third  Avenue,  New  York, 
NY  10028. 

Zero  Length  File  Test 

Being  able  to  determine  whether  a 
file  contains  any  data  before  proceeding 
into  your  main  program  logic  can  be  use¬ 
ful.  In  many  batch  processing  systems  it 
is  not  at  all  uncommon  for  output  files  to 
be  opened  but  never  written  to  because 
of  a  lack  of  the  appropriate  input  records. 
If  the  next  program  in  the  stream  were, 
for  example,  a  print  job,  it  would  be  more 
appropriate  for  it  to  issue  a  message  stat¬ 
ing  that  no  input  is  available  rather  than 
printing  headings  and  totals  with  no  detail 
records. 

I  have  some  experience  with  this  situ¬ 
ation  occurring  with  one  of  the  more 
popular  accounting  systems.  It  is  difficult 
to  explain  a  report  containing  nothing 
but  headings  and  totals  to  a  customer 
who  confronts  you  with  the  question: 
why  print  a  report  when  there  were  no 
data  to  be  printed? 

If  you  have  this  need,  you  may  want 
to  insert  a  short  routine  (see  Listing  One, 
page  100)  in  your  program  at  the  appro¬ 
priate  spot  or  set  it  up  as  a  subroutine  to 
be  called  from  BASIC  or  COBOL. 

PAUSEIF,  QUITIF,  and  now  SKIPIF 

Over  the  past  several  months  two 
programs  to  provide  control  over  submit 
file  processing  (PAUSEIF  and  QUITIF) 
have  been  printed  in  DDJ.  John  Ramsey 
of  Louisville,  Kentucky  has  sent  in  a  third 
which  allows  conditional  command  skip¬ 
ping  to  be  implemented.  The  use  of  these 
three  programs  together  will  undoubtedly 
provide  most  of  the  control  you  may 
need  to  ensure  that  batch  procedures  are 
executed  properly.  A  complete  listing  of 
John’s  program  can  be  found  in  Listing 
Two  (page  101). 

Miscellaneous 

Several  months  ago  I  asked  for  help 
in  finding  patches  for  the  CCP  to  search 
user  area  0  for  .COM  files  not  found  in 
the  current  user  area.  Well,  I  got  what  I 
asked  for!  A  number  of  different  routines 
have  arrived  which  I  want  to  share  with 
anybody  that  is  interested.  If  you  send 
me  a  SASE  #  10  envelope  (business  size) 
I  will  be  happy  to  return  to  you  what  I 
have. 

A  lot  of  good  stuff  is  coming  in  future 
issues.  I  am  just  about  ready  to  rewrite 
my  systems  BIOS  for  CP/M  Plus  which  I 


will  be  putting  into  the  public  domain 
through  this  column  and  in  paperware 
form.  After  it’s  well  tested,  I  will  send  it 
to  either  CPMUG  or  SIG/M  where  you 
can  get  it  on  disk.  Chat  with  you  next 
month. 
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CP/M  Exchange  (Text  begins  on  page  98) 

Listing  One 


;  Short 

routine 

to  test  for  zero  length  files 

fcb 

equ 

0 

first  byte  of  fcb 

f  cbdr 

equ 

fcb 

drive  byte  of  fcb 

f cbf nam 

equ 

fcbdr+1 

first  byte  of  file  name 

f cbf ext 

equ 

f cbf nam+8 

first  byte  of  file  name  extension 

f  cbex 

equ 

fcbf ext+3 

current  extent  number 

f  cbsl 

equ 

fcbex+1 

internal  use  byte 

f  cbs2 

equ 

fcbsl+1 

status  byte  used  by  open 

f  cbrc 

equ 

fcbs2+l 

record  count  for  this  extent 

f  cbdm 

equ 

fcbrc+1 

first  byte  of  data  map 

f  cbcr 

equ 

f cbdm+16 

current  record  number 

f  cbr0 

equ 

fcbcr+1 

16  bit  random  record  number 

f  cbr2 

7 

equ 

f cbr0+2 

overflow  from  R0 

/ 

open 

equ 

15 

BDOS  open  function 

bdos 

equ 

05h 

•BDOS  jump  point 

Id 

push 

Id 

call 
s  tc 

i  nc 
ret 


Pop 

Id 

o  r 


ret 

Listing  Two 


de , pfcb 
de 


load  DE  register  with  address 
of  initialized  fcb  and  save 


c,open  ; BDOS  open  function 

bdos  ; open  file 

;set  carry  flag  to  indicate  error 
; i f  file  was  not  found 
a  ;was  file  available 

z  ;no  -  test  for  carry  at  return 

;point  to  determine  whether  file 
; was  available 

ix  ;load  IX  register  with  fcb  address 

a,(ix+fcbrc)  ;load  a  register  with  number 
;of  records  in  first  extent 
a  ;set  condition  codes  for  testing 

;at  return  point 
;Z  =  zero  length  file 
;NZ  =  non-zero  length  file 
;back  to  caller 

End  Listing  One 


SKIPIF  —  a  submit  utility  for  conditional  command  skipping 

written  by  John  C.  Ramsey 

major  parts  shamelessly  stolen  from: 

QUITIF  in  Dr.  Dobb's  Journal,  No.  71,  Sept.  1982 
written  by  Don  Wright  of  San  Antonio,  TX 

Usage 


SKIPIF  AMBIG  *1  —  skip  next  line  on  ambiguous  name 

SKIPIF  EXISTS  *1  —  skip  next  line  on  pre-existing  file 

SKIPIF  MISSING  $1  —  skip  next  line  on  non-existent  file 

SKIPIF  NULL  $1  —  skip  next  line  on  null  parameter 
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SKIPIF  ZERO  *1 


—  skip  next  line  on  zero  length  -file  or  missing 


Only  the  first  letter  of  the  keyword  is  checked.  A  letter 
other  than  A,  E,  M,  N,  or  Z  (or  an  omitted  keyword)  will  print 
the  help  message  and  have  no  effect  on  the  $$$.SUB  file 


TPA 

EQU 

oiooh  ; 

beginning  of  program  area 

BDOS 

EQU 

0005H  ; 

bdos  entry  point 

FCB1 

EQU 

005CH  ; 

the  default  FCB  in  low  storage 

NAME  1 

EQU 

005DH  ; 

filename  number  1  (keyword) 

FCB2 

EQU 

006CH  ; 

second  parameter,  treated  as 

FCB 

NAME2 

EQU 

006DH  ; 

filename  number  2  (argument) 

DMA 

EQU 

0080H  ; 

buff  for  read/write 

* 

PRTSTR 

EQU 

9  ; 

print  string  until  * 

SELECT 

EQU 

14  ; 

select  disk  function 

OPEN 

EQU 

15  ; 

open  a  file 

CLOSE 

EQU 

16  ; 

close  a  file 

SEARCH 1 

EQU 

17  ; 

search  for  first  matching  name 

ERASE 

EQU 

19  ; 

delete  file 

READ 

EQU 

20  ; 

read  sequential 

WRITE 

EQU 

21  ; 

write  sequential 

MAKE 

EQU 

22  ; 

make  a  file 

RENAME 

EQU 

23  ; 

rename  a  file 

SETDMA 

EQU 

26  ; 

set  DMA  address 

5 

CR 

EQU 

13  ; 

carriage  return 

LF 

EQU 

10  ; 

line  feed 

EOT 

EQU 

'  ; 

end  of  string  marker 

DISKA 

EQU 

o 

■a  i 

function  parameter  for  drive 

a: 

• 

ORG 

TPA 

5 

;  Look 

for  files  on  disk 

a: 

5 

disk: 

MV  I 

E, DISKA 

MV  I 

C, SELECT 

CALL 

BDOS 

9 

;  Check 

for  presence  of 

*$*.SUB  on  disk  A: 

5 

LX  I 

D, SUBFILE 

;  Set  FCB  area 

MV  I 

C, OPEN 

;  Open  file 

CALL 

BDOS 

I  NR 

A 

;  Is  there  a  file? 

JNZ 

XIF 

;  Yes,  so  continue  program 

9 

;  Explain  the 

use  of  the 

program  to  user 

9 

EXIT: 

MV  I 

C, PRTSTR 

;  Load  help  message 

LX  I 

D, HELPMSG 

CALL 

BDOS 

;  ...and  tell  user  about  SKIPIF  program 

5 

RET 

;  exit  to  CCP 

5 

XIF: 

LX  I 

H , NAME 1 

MOV 

A,  M  ; 

get  function  code  letter 

LX  I 

H, NAME2  ; 

point  to  f i 1 ename/par ameter 

(Continued  on  next  page) 
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CP/M  Exchange  (Listing  continued,  text  begins  on  page  98) 

Listing  Two 


CPI 

’A’ 

5 

SKIPIF  AMBIGuous  name 

JZ 

AMBIG 

CPI 

’E’ 

9 

SKIPIF  EXISTS  name 

JZ 

EXISTS 

CPI 

’M’ 

9 

SKIPIF  MISSING  name 

JZ 

MISSING 

CPI 

’N’ 

9 

SKIPIF  NULL  name 

JZ 

NULL 

CPI 

’  Z’ 

5 

SKIPIF  ZERO  length  -file 

JZ 

ZERO 

9 

;  Keyword  is 

none  o-f  the 

above,  explain  use  o-f  the  program  on  way 

9 

9 

JMP 

EXIT 

9 

;  skip 

next 

1  i  ne  i  -f  the 

second  parameter  is  an  ambiguous  name 

5 

AMBIG 

MV  I 

A,  ’  ?' 

CMP 

M 

JZ 

SKIP 

9 

it  is  one  —  go  do  skip 

I  NR 

L 

MOV 

A,  L 

CPI 

NAME2+1 1 

JC 

AMBIG 

9 

continue  to  end  o-f  -filename 

RET 

5 

unambiguous  —  return  to  CCP 

5 

;  skip 

5 

nex  t 

1  i  ne  i  -f  the 

named  -file  does  not  exsist 

5 

EXISTS 

CALL 

SEARCH 

5 

look  -for  the  file 

CPI 

OFFH 

5 

was  there  one? 

RZ 

no  —  return  to  CCP 

JMP 

SKIP 

9 

yes  —  skip  the  next  line  in  submit  fi 

5 

5  skip 

nex  t 

1  i  ne  i  -f  the 

named  -file  does  not  exist 

9 

MISSING 

CALL 

SEARCH 

5 

look  for  the  file 

CPI 

OFFH 

9 

was  there  one? 

RNZ 

5 

yes  —  return  to  CCP 

JMP 

SKIP 

5 

no  —  skip  the  next  line  in  submit  file 

9 

5  skip 

nex  t 

1  i  ne  i  -f  the 

second  parameter  was  null,  i.e.  all  blank 

5 

NULL 

MV  I 

A,'  ' 

CMP 

M 

5 

test  filename 

RNZ 

5 

...  not  nul 1 ,  return  to  CCP 

LX  I 

H, NAME2+8 

CMP 

M 

• 

test  file  extension 

RNZ 

■ 

9 

...  not  nul 1 

LDA 

FCB2 

9 

test  for  a  drivecode  alone 

ORA 

A 

RNZ 

5 

. .  . "d:  "  given  alone 

JMP 

SKIP 

5 

drive,  name,  extension,  all  null 

9 

;  abort 
5 

i -f  the  -filename 

has  a  length  o-f  Zero 
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ZERO 

5 


CALL 


MISSING  ;  First  o-f  all,  is  -file  there? 


MV  I 
LX  I 
CALL 

MV  I 
LX  I 
CALL 
ORA 
RZ 


C, OPEN  ;  Open  it  if  so 

D,  FCB2 
BDOS 

C ,  READ 

D,  FCB2 
BDOS 

A 


SKIP 


;  read  was  successful ,  return  to  CCP 
;  skip  next  line  i-f  end  o-f  file  occurred 


;  Delete  next  record  by  recopying  file  $$$.SUB  to  $$$.TMP 
;  except  for  the  last  record  (which  is  the  next  command) 

;  then  delete  old  $$$.SUB  and  rename  $$$.TMP  to  $$$.SUB 


SKIP:  MV I 

LX  I 
CALL 

MV  I 
LX  I 
CALL 

MV  I 
LX  I 
CALL 
MV  I 
LX  I 
CALL 


LX  I 
CALL 
MV  I 
LX  I 
CALL 


C,  ERASE 

D,  TMPFILE 
BDOS 

C ,  MAKE 

D,  TMPFILE 
BDOS 

C,  SETDMA 

D,  DMA 
BDOS 

C,  READ 

D,  SUBFILE 
BDOS 

C,  SETDMA 

D,  LASTR 
BDOS 

C,  READ 

D,  SUBFILE 
BDOS 

A 

CLEAR 


;  Make  sure  *$$.TMP  isn't  there 
;  before  making  it 


;  Make  TMP  (thus  opening  it) 

;  This  is  the  default  but  do  anyhow 
;  point  to  80h  buffer 

;  read  first  record  in  file  (last  command) 
;  info  now  at  DMA  at  80h  buffer  (#1) 


;  location  of  buffer  #2 
;  change  DMA  address  to  buffer  #2 

;  read  record  #2  into  buffer  #2 


;  end  of  f i 1 e? 

;  if  so  go  finish  up 


staggered  transfer  —  by  switching  the  DMA  between  2  record  buffers 
this  part  transfers  $$$.SUB  to  $$$.TMP  BUT  with  an  offset  of  one, 
(read  #3,  write  .  When  EOF  of  $*$.SUB  is  reached,  we  exit  the 

loop  without  WRITing  the  last  record,  (which  is  the  next  command) 
thus  SKIPPING  it. 


MV  I 

C, SETDMA 

5 

wor  k 

with  buffer  #1 

LX  I 

D,  DMA 

CALL 

BDOS 

MV  I 

C, WRITE 

5 

get 

rec  from  #1,  write 

LX  I 

D, TMPFILE 

CALL 

BDOS 

MV  I 

C ,  READ 

5 

read 

from  SUB,  put  rec 

LX  I 

D, SUBFILE 

CALL 

BDOS 

(Continued  on  next  page) 
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CP/M  Exchange  (Listing  continued,  text  begins  on  page  98) 

Listing  Two 

5 

ORA 

A 

5 

end  o-f  f i  1  e? 

JNZ 

DONE 

5 

i  f  so  go  -finish  up  without  writing  last  rec 

5 

MV  I 

C , SETDMA 

LX  I 

D,LASTR 

5 

work  with  buffer  #2 

CALL 

BDQS 

MV  I 

C, WRITE 

5 

get  rec  -from  #2,  write  to  TMP 

LX  I 

D, TMPFILE 

CALL 

BDOS 

MV  I 

C, READ 

9 

read  -from  SUB,  put  rec  in  #2 

LX  I 

D, SUBFILE 

CALL 

BDOS 

5 

ORA 

A 

9 

end  o-f  file? 

JNZ 

CLEAR 

9 

if  so  go  finish  up  without  writing  last  rec 

5 

JMP 

TRANS 

9 

do  it  again  until  eof 

clear: 

MV  I 

C, SETDMA  ;  Clear  default  DMA 

LX  I 

D,  DMA 

CALL 

BDOS 

MV  I 

C, WRITE 

LX  I 

D, SUBFILE 

CALL 

BDOS 

9 

DONE: 

MV  I 

C, CLOSE  ;  save  new  **$.TMP  file 

LX  I 

D, TMPFILE 

CALL 

BDOS 

9 

MV  I 

C, ERASE  ;  erase  old  $$$.SUB  file 

LX  I 

D, SUBFILE 

CALL 

BDOS 

9 

MV  I 

C, RENAME  ;  rename  *$*.TMP  to  $*$.SUB 

LX  I 

D, RENFILE 

CALL 

BDOS 

9 

MV  I 

C,PRTSTR  ;  tell  user  program  worked 

LX  I 

D, SKIPMSS 

CALL 

BDOS 

RET 

;  exit  to  CCP 

9 

;  subroutine 

to  use  the  search-for-the-f irst-match  function 

9 

SEARCH 

MV  I 

C, SEARCH 1 

LX  I 

D, FCB2 

CALL 

BDOS  ;  find  first  matching  name 

5 

RET 

;  return  A=ff,  00,  01,  02,  03 

5 

SUBFILE 

DB 

SUB' 

DB 

0,0, 0,0, 0,0, 0,0, 0,0 

DB 

0,0, 0,0, 0,0, 0,0, 0,0 

DB 

0,0, 0,0, 0,0, 0,0, 0,0 
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TMPFILE  DB  1 , ’ ***  TMP' 

DB  O,  O,  O,  O,  O,  O,  O,  O,  O,  0 

DB  O,  O,  O,  O,  O,  O,  O,  O,  O,  O 

DB  0,0, 0,0, 0,0, 0,0, 0,0 

5 

RENFILE  DB  1,'***  TMP’ 

DB  0,0, 0,0 

DB  1,’***  SUB’ 

DB  0,0, 0,0 

i 

SKIPMSG  DB  CR, LF, ’ The  above  condition  is  true. ’ , CR, LF, CR, LF 

DB  ’The  next  line  has  been  DELETED. ’, CR, LF, EOT 

5 

HELPMSG  DB  ’~C*’ 

DB  ’SKIPIF  is  a  program  to  be  used  with  SUBMIT’ , CR, LF 

DB  CR, LF 

DB  ’Usage: ’ ,CR,LF 

DB  ’ - ’  ,  CR ,  LF 

DB  ’  SKIPIF  AMBIG  file  —  skip  next  line  if  ambiguous  name’ 

DB  CR, LF 

DB  ’  SKIPIF  EXISTS  file  -  skip  next  line  if  pre-existing  file’ 

DB  CR, LF 

DB  ’  SKIPIF  MISSING  file  -  skip  next  line  if  non-existent  file’ 

DB  CR, LF 

DB  ’  SKIPIF  NULL  file  —  skip  next  line  if  null  parameter’ 

DB  CR, LF 

DB  ’  SKIPIF  ZERO  file  -  skip  next  line  if  zero  length  file’ 

DB  CR, LF, CR, LF 

DB  ’Only  the  first  letter  of  the  keyword  is  checked.  A  letter’ 

DB  CR, LF 

DB  ’other  than  A,  E,  M,  N,  or  Z  (or  an  omitted  keyword)  will’ 

DB  CR, LF 

DB  ’display  these  instructions  but  have  no  effect  on  the  submit’ 

DB  CR, LF 

DB  ’file.  Parameters  or  actual  file  names  may  be  used  in’ 

DB  CR, LF 

DB  'the  submit  file  as  arguments  to  SKIPIF.’ 

DB  CR, LF 

DB  EOT 

5 

;  data  area 
5 

LASTR:  DS  129  ;  buffer 

> 

END  X  I F 


End  Listing  Two 
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SOFTWARE  REVIEW 


ACTxx  Cross  Assemblers 


From  SORCIM,  2310  Lundy  Avenue, 

San  Jose,  CA  95131 
Requires  CP/M  1.4  or  better 

with  32K  of  RAM 
$175  each 

Reviewed  by  Steve  Newberry 

For  some  time  now  I  have  urged  that 
microprocessor  manufacturers  should 
make  8080-hosted  cross-assemblers  for 
their  processors  available  if  they  are  really 
interested  in  selling  chips  (instead  of  de¬ 
velopment  systems).  For  every  develop¬ 
ment  system  capable  of  producing  code 
for  a  given  processor,  XYZ,  there  are  at 
least  ten  8080/Z80-based  systems  run¬ 
ning  on  CP/M,  and  I  leave  it  to  you  to 
guess  at  the  number  of  8080/Z80  prod¬ 
ucts  that  have  been  developed  on  these 
systems. 

Alas,  to  no  avail.  Cross-assemblers 
that  have  been  offered  in  the  past  have 
generally  been  written  in  ANSI  Fortran 
and  only  been  accessible  on  the  maxi¬ 
computers  —  at  nontrivial  hourly  rates. 
The  motives  for  such  a  policy  may  have 
seemed  plausible  at  the  time,  but  the 
practical  consequences  have  proven  to  be 
less  than  ideal.  In  order  to  do  develop¬ 
ment  work  for  the  XYZ  processor  one 
had  to  have  either  access  to  an  XYZ  de¬ 
velopment  system  running  the  resident 
assembler  or  to  a  mainframe  (usually  a 
370)  running  the  cross-assembler.  Either 
approach  imposed  an  initial  overhead  (for 
rental  fees  alone! )  of  such  magnitude  that 
hundreds  (thousands?)  of  projects  which 
might  have  been  developed  for  the  XYZ 
were  never  undertaken.  One  may  certain¬ 
ly  speculate  about  the  consequent  loss  of 
sales  (and  jobs!)  which  might  have 
resulted. 

Fortunately,  the  small  software  houses 
are  beginning  to  address  themselves  to 
this  need,  and  it  is  now  possible  to  pur¬ 
chase  8080-hosted  cross-assemblers  for 
all  the  major  micros  except  the  Z8000 
and  the  MC68000. 

Sorcim,  the  producer  of  Pascal/ M 
and  Supercalc,  has  for  nearly  two  years 
been  distributing  a  family  of  cross- 
assemblers  which  run  on  the  8080  under 
CP/M  and  generate  code  for  8080,  Z80, 
6502,  6800,  8086/8088,  and  6809.  The 
family  is  called  ACT  (“Assembly  Coded 
Translator”),  and  each  assembler  package 
is  called  ACTxx  (where  “xx”  is  one  of: 
80,  65,  68,  86,  or  69).  The  current  release. 
Version  3.5,  consists  of  a  CP/M-compatible, 
8 -inch  diskette  and  a  70-plus  page  User’s 
Reference  Manual.  The  ACTxx  diskette 


contains  seven  files  (eight  in  the  case  of 
ACT80): 

ACTxx.COM  —  assembler 
DOCOPxx.asm  —  source  file  contain¬ 
ing  all  ACTxx  mnemonics 
IPARAMS.acd  —  file  of  definitions 
common  to  all  assemblers 
ACD/EG.asm  —  example  demonstrat¬ 
ing  use  of  LINK  pseudo-op 
UTIL.acd  —  utility  subroutines  (ACT- 
80  only) 

DATTIM.com  —  sets  Date  and  Time 
for  ACTxx  listing  header 
INSTALLA.sub  —  copies  ACT  sys¬ 
tem  to  system  disk  under  CP/M 
INSTALLC.cmd  —  copies  ACT  sys¬ 
tem  to  system  disk  under  CDOS 

The  manual  is  punched  for  a  three-hole 
binder.  There  is  no  index,  but  the  Table 
of  Contents  is  intelligently  done,  and  all 
the  information  is  conveniently  accessi¬ 
ble.  The  command  line  to  CP/M  invoking 
ACTxx  follows  the  same  protocol  as  that 
of  Pascal/ M,  for  example: 

A>ACT80  <filename>  <cr> 

assembles  <filename>,  puts  the  (abso¬ 
lute)  hex  file  on  the  selected  disk  under 
the  name  <  filename>.hex,  and  doesn’t 
give  you  a  listing  unless  you  ask  for  it. 

Assembly  is  extremely  rapid.  I  used 
RELOC.ASM  (from  the  CPMUG  library) 
as  a  benchmark  and  timed  ACT80  against 
the  CP/M  assembler  ASM.  (ASM  is  really 
fast.)  RELOC  is  a  10K  file  which  ASM 
assembled  in  16  seconds  as  compared  to 
18  seconds  for  ACT80.  (The  tests  were 
run  on  a  4  MHz  Z80  with  a  double-density 
8-inch  floppy  disk.)  That  means  that  the 
very  substantially  increased  power  of 
ACT80  over  ASM  (macros,  many  pseudos) 
is  purchased  at  about  a  10%  increase  in 
assembly  time.  (MAC  also  ran  the  same 
job  in  18  seconds.) 

Although  the  other  cross-assemblers 
were  not  compared  for  speed,  they  should 
be  comparable  because  of  the  way  in 
which  they  are  implemented.  The  whole 
macro  expansion  portion  is  constant  from 
one  assembler  to  another;  the  only  thing 
that  changes  is  the  table  containing  the 
pseudo  instructions,  the  target  machine 
mnemonics,  and  the  corresponding  ma¬ 
chine  codes. 

8080 -Resident  and  Z80 
Cross-Assembler 

ACT80  will  assemble  both  for  the 
8080/8085  and  for  the  Z80.  Originally, 


the  assembler  had  been  produced  for 
Sorcim  in-house  use  in  writing  Pascal/M. 
Since  the  programmers  were  already 
familiar  with  the  mnemonics  for  CDC 
mainframes,  the  Sorcim  mnemonics  ini¬ 
tially  had  a  distinctively  CDC-like  flavor. 
When  it  was  decided  to  market  the  ACT 
family  of  cross-assemblers,  the  mnemonics 
were  extended  to  include  the  entire  Intel 
set  (including  the  ’85  RIM  and  SIM  in¬ 
struction).  The  Zilog  set  is  still  only 
partially  represented,  although  there  are 
“Zilog-like”  mnemonics  which  complete 
the  Z80  instruction  set.  However,  the 
Sorcim  mnemonics  regard  movement  be¬ 
tween  registers  as  moves  (MOV),  but 
memory-register  moves  as  loads  (LD), 
register- memory  moves  as  stores  (STO), 
and  constant -register  moves  as  load- 
constants  (LK). 

In  other  words,  Z80  programs  writ¬ 
ten  on  ACT80  can  be  assembled  with 
only  a  little  massaging  (a  few  macros  in 
ED  or  WM),  by  translators  which  recog¬ 
nize  the  standard  Zilog  set  of  mnemonics, 
but  transforming  source  programs  in  the 
Zilog  notation  to  the  Sorcim  set  is  rather 
tedious. 


6502  Cross-Assembler 

Turning  to  the  other  cross-assemblers, 
we  find  that  ACT65  recognizes  the  MOS 
Technology  mnemonics  with  only  three 
exceptions,  and  these  are  trivial  to  trans¬ 
late  in  either  direction: 

(1 )  MOS  Technology  encloses  address  ex¬ 
pressions  in  round  parentheses  where 
Sorcim  uses  square  brackets. 

(2)  Some  6502  assemblers  use  a  single 
prefixed  quote-mark  (apostrophe)  to 
signal  a  one -character  string.  Sorcim 
requires  that  all  strings  be  enclosed 
between  balanced  quote- pairs. 

(3)  In  the  Sorcim  assemblers,  the  symbols 
“<  ”  and  “>”  are  only  used  as  bi¬ 
nary  operators,  and  the  correspond¬ 
ing  unary  operators  are  “low”  and 
“high.” 

6800  Cross-Assembler 

The  ACT68  mnemonics  are  a  com¬ 
patible  superset  of  the  Motorola  6800  set, 
and  only  minor  differences  exist  in  ex¬ 
pression  evaluation  and  pseudos: 

(1)  ACT68  observes  normal  operator 
precedence. 

(2)  ACT68  requires  that  quote  marks 
demarcating  character  strings  be 
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paired  (as  in  the  ACT65  case  noted 
above). 

(3)  ACT68  does  not  support 

NAM  (use  TITLE  instead) 

MON 

OPT  (use  LIST  instead) 

(4)  ACT68  requires  that  comments  be 
preceded  by  semicolon  (or  asterisk  if 
in  column  one). 

8086/8088  Cross-Assembler 

To  appreciate  the  difference  between 
the  Intel  and  the  Sorcim  8086/8088  as¬ 
sembler  mnemonic  sets,  it  is  helpful  to 
know  something  about  the  structure  of 
the  Intel  assembler  MCS-86. 

In  designing  a  mnemonic  instruction 
set,  one  usually  attempts  to  strike  a  bal¬ 
ance  between  two  desirable  but  mutually 
incompatible  ends:  (1)  a  small  simple  fast 
assembler  program,  and  (2)  a  small  simple 
easily  learned  set  of  mnemonic  operator 
names. 

When  the  instruction  set  is  small  to 
begin  with,  the  problem  is  fairly  tractable, 
but  as  the  instruction  set  grows,  it  be¬ 
comes  necessary  to  resort  to  the  device  of 
“operator  overloading”  to  keep  the  dis¬ 
tinct  mnemonics  down  to  a  reasonable 
number.  This  means  that  the  assembler 
must  be  capable  of  recognizing  that  an 
operator  can  take  several  different  cate¬ 
gories  of  operand  and  be  able  to  distin¬ 
guish  these  categories  correctly. 

For  example,  the  Zilog  mnemonics 
for  the  Z80  compress  all  the  LOAD, 
LOADCONSTANT,  STORE,  and  MOVE 
operations  into  the  single  mnemonic 
“LD,”  and  give  to  the  assembler  the  re¬ 
sponsibility  of  distinguishing  between 
registers  and  memory  and  constants,  as 
well  as  operand  lengths  (byte  versus 
word).  This  makes  for  a  larger,  more 
complex  (expensive),  slower  assembler, 
but  also  makes  it  much  easier  for  the  pro¬ 
grammer  to  learn  the  machine. 

The  designers  of  the  Intel  MCS-86 
assembler  saw  fit  to  “make  a  virtue  of 
necessity”  by  making  the  MCS-86  assem¬ 
bly  language  a  strongly  typed  language. 
Thus,  in  MCS-86  (as  in  Pascal  and  Ada) 
the  assembler  looks  up  the  number  of 
bytes  assigned  to  a  variable  every  time 
that  variable  is  accessed  in  the  source 
code,  and  checks  that  only  arguments  of 
the  same  length  may  be  acted  upon  by  a 
single  operation.  (There  is  an  override, 
but  it  is  not  relevant  here.)  Aside  from 
enforcing  an  additional  level  of  assembly¬ 
time  error  checking,  this  also  permits  the 
large  instruction  set  of  the  8086  to  be 
compressed  into  a  much  smaller,  highly 
overloaded  set  of  mnemonics. 

Sorcim  adheres  to  the  Intel  mne¬ 
monics  almost  as  nearly  as  can  be  accom¬ 
plished  without  actually  going  over  to 
the  strongly  typed  restrictions  of  MCS- 
86.  This  is  largely  accomplished  by  dis¬ 
tinguishing  word  from  byte  operations 


through  a  “B  suffix”  convention.  In 
effect,  the  programmer  learns  (almost) 
the  same  set  of  mnemonics,  but  is  required 
to  inform  the  assembler  when  byte 
operands  are  forthcoming  by  suffixing 
the  letter  “B”  to  the  operator  mnemonic. 
Thus,  an  ADD  instruction  is  applied  to 
byte  (rather  than  word)  operands  by 
writing  ADDB.  The  other  differences  are 
(1)  ACT86,  like  its  siblings,  also  differen¬ 
tiates  between  register-register  MOVes, 
register-memory  STOres,  and  memory- 
register  LoaDs;  and  (2)  the  “destination, 
source”  ordering  of  operands  is  reversed 
in  the  case  of  the  STOre  instructions. 

Here  again,  the  practical  consequences 
are  that  it  is  easy  to  transport  ACT86 
source  code  to  MCS-86  (by  defining 
macros  to  delete  all  the  “B  suffixes,” 
replace  the  LD  and  STO,  etc.)  but  rather 
tedious  to  port  in  the  other  direction. 

6809  Cross-Assembler 

The  remarks  concerning  ACT68  apply 
here  as  well.  There  are  two  additional 
pseudos:  SETDP  (sets  the  assembler’s 
pseudo  Direct  Page  Register),  and  FAIL 
(synonym  for  ERR).  ACT69  also  does 
not  support  the  Motorola  REG  pseudo. 
Otherwise  the  Sorcim  mnemonics  are  a 
compatible  superset  of  the  Motorola 
standard. 

Features  Common  to 
All  Members  of  the  Family 

Command  line  options  allow  you  to: 
specify  the  disk  drive  to  which  the  hexfile 
will  be  sent  (or  you  may  send  no  hexfile 
at  all),  specify  the  destination  of  the  list- 
file  ( lineprinter,  console,  diskdrive,  of  no 
listfile),  set  page  size  (defaults  to  PS=58), 
set  line  length  (defaults  to  SL=140), 
specify  either  of  two  flavors  of  cross- 
reference  map  (default  lists  globals  only), 
specify  library  files  to  be  linked  in  with 
the  program,  and  specify  the  origin  (ORG) 
at  which  the  program  is  to  be  loaded.  The 
manual  is  very  clear  about  how  to  specify 
these  options. 

The  pseudos  include  the  standard  set 
you’d  expect  to  find:  DB,  DW,  DS,  ORG, 
EQU,  SET,  PAGE  (or  EJECT),  TITLE, 
SPACE,  the  conditional  assembly  controls 
IF,  ELSE,  ENDIF,  a  toggle  (LIST)  to 
control  listings  (invaluable  in  debugging 
macros),  END,  LINK  (approximately 
equivalent  to  SINCLUDE  or  MACLIB), 
MACRO/ENDMACRO,  and  several  built- 
in  macros.  Macros  may  take  up  to  nine 
parameters  and  may  be  tested. 

In  addition  to  these  are  several 
pseudos  which  call  for  special  comment. 
LOC  permits  you  to  assemble  a  chunk  of 
code  to  LOAD  at  a  different  address  than 
that  at  which  it  is  to  execute,  load  it  at 
the  ORG  address,  then  move  it  to  the 
LOC  address  and  execute.  This  sort  of 
thing  arises  when  programs  or  pieces  of 
programs  in  ROM  need  to  be  moved  to 
RAM  for  execution,  or  in  writing  transient 


device  drivers  which  are  to  be  relocated 
to  lie  just  beneath  the  operating  system. 
You  may  not  use  LOC  very  often,  but 
when  you  do  need  it  you’ll  bless  the  de¬ 
signer  of  ACT  for  having  provided  it. 

Another  nice  touch  is  VFD.  This 
permits  you  to  write  your  own  assembler 
(for  some  other  processor)  in  an  intelli¬ 
gent  manner.  Of  course,  the  macro  facil¬ 
ity  would  allow  you  to  grind  out  an 
assembler  by  writing  a  separate  macro  for 
every  possible  opcode  —  but  this  would 
entail  writing  out  hundreds  (or  even  thou¬ 
sands!)  of  separate  macros.  VFD  permits 
you  to  specify  arbitrary  bit- fields  within 
a  byte.  In  this  way  you  can  construct 
your  assembler  the  way  it  should  be  done: 
as  a  fixed  pattern  of  bits  for  each  generic 
opcode,  with  variations  in  particular  bit  - 
fields  specifying  the  source/destination 
operands.  (To  find  a  feature  like  this  in  a 
$175.00  assembler  is  extraordinary! ) 

The  file  IPARAMS.acd  is  a  library 
file  of  symbol  definitions:  EQU’s  for  the 
standard  ASCII  control  characters  and 
the  CP/M  system -call  functions  and 
magic  entry -points.  I  found  it  convenient 
to  edit  in  an  “END”  statement  and  adopt 
the  convention  that  all  programs  are  ter¬ 
minated  With  a  “LINK  IPARAMS.ACD” 
statement.  The  file  UTIL.acd  (found  only 
in  the  ACT80  package)  contains  several 
flavors  of  string  move/compare,  block-fill, 
and  other  commonly  used  functions. 

Another  thing  I  like  about  these  as¬ 
semblers  is  their  ability  to  treat  all  letters 
as  though  they  were  upper  case  without 
forcing  lower-case  to  upper-case  con¬ 
version  on  the  listing.  It’s  much  easier  to 
read  a  listing  when  it  looks  like  the  origi¬ 
nal  source!  The  ACT  assemblers  also  allow 
you  to  use  “ _ ”,  “ .  and  “  #  ”  as  separa¬ 
tion  (“break”)  characters.  ACT  treats 
the  underline  as  a  “ghost”  character 
(it  is  not  significant).  Thus,  you  can  write 
variable  names  and  labels  as  things  like 
“iteration_#”  or  “error.exit”.  All  this 
makes  it  convenient  to  write  very  read¬ 
able  source  and  to  generate  very  readable 
listings.  And  that  means  time  and  money 
saved  in  development  and  maintenance. 

»»r 

Sorcim  also  provides  the  same  packages 
for  a  variety  of  other  chips  besides  the 
8080.  Contact  them  for  details.  —Ed. 
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BOOK  REVIEWS 


Microcomputer  Disk  Techniques 

By  Paul  Swanson 

Published  by  BYTE/McGraw-Hill 

234  pages,  $15.00 

Reviewed  by  George  W.  Jolly 

When  you  bought  your  shiny  new 
computer,  you  probably  picked  one  with 
as  much  phaser  power  as  you  could  find. 
You  took  it  home,  connected  all  the 
cables,  and  found  you  could  zap  klingons 
with  the  best  of  them.  Soon,  however, 
you  noticed  something,  a  voice,  whisper¬ 
ing  in  your  ear.  You  tried  to  ignore  it,  but 
each  day  it  grew  louder  and  louder.  Even¬ 
tually  you  were  forced  to  face  the  ques¬ 
tion,  “How  can  I  do  something  useful 
with  this  thing?” 

Stoically,  you  reached  for  the  BASIC 
manual  that  came  with  the  computer  and 
began  to  read.  You  learned  about  varia¬ 
bles,  subroutines  and  statement  labels. 
With  some  fascination  you  read  about  se¬ 
quential  disk  files,  which  must  be  read  in 
the  same  order  they  were  written.  You 
moved  on  to  random-access  files,  and 
learned  that  you  could  read  or  write 
items  in  any  order  you  pleased.  With  such 
tools  you  could  handle  nearly  any  task  — 
once  you  chose  a  task! 

With  all  this  new  knowledge,  you  set 
about  programming  your  first  application 
program.  As  the  program  grew,  you  real¬ 
ized  that  your  tools  were  more  detailed 
than  your  imagination.  Each  feature  you 
added  to  the  program  made  it  harder  and 
harder  to  remember  how  everything 
works.  Worse,  those  disk  files  were  not 
nearly  as  fast  as  you  had  thought.  What 
went  wrong? 

What  probably  went  wrong  is  two¬ 
fold.  Firstly,  your  program  was  not 
planned  well  enough  in  advance.  Good 
planning  keeps  the  program  readable  even 
after  it  has  become  a  large  program.  Sec¬ 
ondly,  the  BASIC  system  only  provides 
very  simple  methods  of  accessing  disk 
files.  In  order  to  use  files  well  you  need 
to  write  routines  that  are  more  intelligent 
about  disk  files  than  is  BASIC  itself. 

Paul  Swanson,  who  heads  a  computer 
consulting  firm,  effectively  shares  his  ex¬ 
perience  in  both  program  design  and  disk 
file  usage.  He  presents  source  listings  for 
subroutines  that  implement  several  dif¬ 
ferent  file  structures.  Through  the  book, 
these  routines  are  modified  to  meet  other 
needs.  You  can  learn  as  much  about  pro¬ 
gram  structure  in  BASIC  as  about  disk 
handling  from  this  book. 

Most  of  the  book  is  based  on  TRS-80 
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BASIC.  A  large  appendix  revises  the  list¬ 
ings  for  the  Apple  II  and  discusses  the  dif¬ 
ferences.  The  ideas  discussed  are  valuable 
in  themselves,  and  a  user  of  a  different 
language  altogether  would  profit  from  the 
reading.  My  own  experience  says  you  can 
never  see  too  many  examples  of  good 
design.  One  often-overlooked  issue  is  the 
design  of  the  user  interface.  Questions 
properly  presented  to  the  user  are  easier 
to  answer,  and  the  program  should  recog¬ 
nize  erroneous  entries  intelligently.  Author 
Swanson  has  a  good  discussion  of  this 
topic. 

The  book  presents  informal  dis¬ 
cussions,  program  listings,  and  detailed 
explanations  of  the  programs.  Amusing 
drawings  by  Eddie  Germano  enhance 
the  reading  experience,  as  does  author 
Swanson’s  easy  prose  style.  Concepts  are 
developed  from  the  ground  up,  and  the 
explanations  are  clear.  This  book  should 
be  a  help  in  designing  useful  software. 


Microcomputer  Design  and  Construction 
By  Alan  Clements 

Published  by  Prentice/ Hall  International 
520  pages,  $32.00 
Reviewed  by  George  W.  Jolly 

Alan  Clements  has  packed  this  book 
with  surprises,  all  pleasant.  Basically  a 
text  about  microcomputer  systems,  this 
book  is  really  a  diary  of  the  author’s  own 
design  experiences.  Although  his  system 
is  based  on  the  Motorola  6800  CPU,  the 
book’s  value  is  not  limited  to  6800  sys¬ 
tems.  At  every  turn  unusual  tidbits  of 
information  appear.  The  author  does  an 
excellent  job  of  presenting  engineering 
concepts  to  non-engineers. 

Clements  explains  the  structure  of  a 
microcomputer  system,  showing  relation¬ 
ships  between  the  basic  components.  His 
explanations  of  timing  diagrams  and  tim¬ 
ing  compatibility  are  excellent.  The  em¬ 
phasis  is  on  understanding  the  subject 
well  enough  to  design  a  system  yourself. 
The  writing  style  throughout  is  clear  and 
the  illustrations  are  most  helpful. 

One  real  plus  comes  from  the  author’s 
familiarity  with  computer  components. 
He  describes  several  chips  that  are  not 
commonly  found  in  magazine  articles. 
One  is  the  field-programmable  logic  array, 
a  variant  of  which  is  used  for  address  de¬ 
coding  in  the  illustrated  system.  Another 


area  of  interest  concerns  numeric  chips. 
The  author  describes  the  Am9511  numeric 
processor  and  the  MPY-8HJ  8-bit  parallel 
multiplier.  Digital/analog  conversion  re¬ 
ceives  very  good  treatment,  and  the  prob¬ 
lem  of  sampling  an  audio  signal  properly 
is  explained  well. 

One  subject  which  is  not  as  fully 
developed  as  this  reviewer  would  have 
liked  is  multiple  processor  systems.  The 
author’s  example  connects  a  6802  CPU 
board  to  the  main  system  with  a  serial 
data  link.  Although  this  is  an  interesting 
area  in  itself,  the  6800  architecture  dis¬ 
cussion  earlier  in  the  book  had  hinted  at 
connecting  two  CPUs  directly  in  the  same 
system.  Still,  many  books  unfortunately 
leave  this  topic  out  altogether. 

Most  microcomputer  design  books 
cover  the  same  basic  topics,  because  most 
microcomputers  contain  the  same  basic 
functions.  They  also  generally  omit  the 
same  topics,  because  they  are  considered 
too  complex  for  beginning  designs. 

What  distinguishes  this  book  is  the 
depth  of  information  given.  For  example, 
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Interfacing  to  S-100/  IEEE-696  Micro¬ 
computers,  reviewed  in  an  earlier  issue, 
mentioned  that  the  layout  of  a  dynamic 
memory  board  is  critical,  but  does  not 
tell  why.  Microcomputer  Design  and  Con¬ 
struction  specifically  discusses  the  nature 
of  the  problem  —  dynamic  memory  chips 
have  rapidly  varying  power  requirements. 
Their  sudden  power  demands  make  more 
noise  than  the  steady,  albeit  higher,  power 
demands  of  static  memory.  Although 
neither  book  presents  dynamic  memory 
designs.  Dr.  Clements  has  room  in  the 
textbook  format  to  flesh  out  the  story. 

This  is  a  textbook,  with  exercises  at 
the  end  of  each  chapter.  It  is  an  excellent 
book  for  someone  considering  designing 
their  first  microcomputer  system,  whether 
or  not  he  or  she  uses  the  6800  CPU. 


Pascal  Implementation:  The  P4  Compiler 
By  S.  Pemberton  and  M.C.  Daniels 
Published  by  Ellis  Horwood,  Ltd.  (Eng.) 

and  by  John  Wiley  &  Sons  (U.S.) 

290  pages,  $64.95  hardbound 
Reviewed  by  William  G.  Hutchison,  Jr. 

Several  years  ago  I  evaluated  the  cost 
of  implementing  P4  Pascal  on  a  minicom¬ 
puter  which  shall  remain  nameless.  At 
that  time,  there  were  two  serious  obsta¬ 
cles:  the  sketchy  documentation  supplied 
with  the  implementation  kit,  and  the 
poor  quality  of  the  compilers.  Today’s 
minicomputer  compilers  are  no  better, 
but  the  documentation  problem  is  solved. 

Steven  Pemberton  and  Martin  Daniels 
have  done  a  thorough  job  of  describing 
the  internal  anatomy  of  the  portable  Pas¬ 
cal  compiler  version  4  (P4).  They  wrote 
this  book  with  the  assistance  of  Niklaus 
Wirth  himself,  originator  of  Pascal.  They 
are  frank  about  the  shortcomings  of  the 
compiler.  Here  is  my  favorite  comment: 

The  treatment  of  the  1  .  .  10  case 
is  verging  on  the  abominable.  The 
jump  from  the  then  part  of  an  if 
statement  into  its  else  part  is  proba¬ 
bly  the  worst  bit  of  programming 
in  the  compiler.  It  is  unlikely  that 
Pascal  even  allows  it,  and  it  should 
certainly  be  rewritten. 

This  is  on  page  27,  regarding  proce¬ 
dure  “insymbol.”  The  comment  sounds 
sarcastic,  until  you  realize  that  it  is  prob¬ 
ably  an  afterthought  from  Wirth  or  Urs 
Ammann.  Actually,  this  sort  of  commen¬ 
tary  is  very  valuable.  It  shows  that  the 
book  is  not  superficial  and  not  a  white¬ 
wash.  The  authors  show  flaws  and  limita¬ 
tions,  then  point  out  a  way  to  work 
around  the  problem  or  solve  it. 

The  book  is  organized  one  chapter 
per  major  section  of  the  compiler.  Each 
chapter  begins  with  theory  and  descrip¬ 
tion,  then  gets  down  to  a  line-by-line 
description  of  the  compiler  source  code. 
These  line  numbers  refer  to  the  version 
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of  P4  which  is  reprinted  in  the  companion 
volume  Pascal  Implementation:  Compiler 
and  Assembler/ Interpreter.  You  should 
buy  both  books  to  be  sure  that  you  can 
follow  the  comments.  If  you  get  a  differ¬ 
ent  release  of  P4,  the  line  numbers  may 
be  different.  The  publishers  of  these 
books  offer  a  tape  version  of  P4.  It  would 
make  sense  to  get  this  for  purposes  of 
cro  ss  -  re  f  ere  ncing. 

In  addition  to  the  commentary,  there 
are  helpful  diagrams  of  the  data  structures 
used  in  the  compiler  and  interpreter.  The 
description  of  the  p-code  instruction  set 
is  a  great  improvement  over  the  brief 
brochure  included  with  the  source  tape. 

Obviously,  this  book  is  intended  for 
experts.  You  have  no  chance  of  under¬ 
standing  it  without  a  thorough  knowledge 
of  Pascal.  It  probably  wouldn’t  do  for  a 
textbook,  because  parts  are  pretty  terse, 
and  there  are  no  formal  exercises.  How¬ 
ever,  an  enterprising  teacher  could  build  a 
dandy  semester  course  around  it  by  hav¬ 
ing  the  students  pursue  some  of  the  hints 
for  improving  the  compiler.  These  hints 
are  numerous  and  shrewd.  For  a  year 
course,  how  about  going  whole  hog  and 
extending  it  to  ISO  standard? 

There  are  a  few  typos:  on  p.  30,  if 
option. list  should  be  if  options.list.  On  p. 
37,  1/21975  should  be  (1975).  On  p.  48, 
b=  record  j:integer;  next;  ta  end  ; 
should  be 

b=  record  j integer;  next:  ta  end  ; 

These  typos  are  not  serious  and  do  not 
alter  the  sense  of  the  text. 

I’ve  saved  one  of  the  best  features  for 
last.  The  appendices  of  the  book  contain 
a  listing  of  all  procedure  and  function 
headers  by  line  number,  a  cross-reference 
of  uses  of  error  numbers  in  the  compiler, 
a  list  of  code  generation  procedure  calls  by 
line  number,  and  a  symbol  cross-reference 
of  the  compiler  and  interpreter  (keyed  to 
the  line  numbers  in  the  other  volume). 
The  original  authors  of  P4  should  have  in¬ 
cluded  these  helpful  indices  with  the 
source,  but  they  didn’t.  Pemberton  and 
Daniels  have  come  to  the  rescue. 

If  you  want  to  implement  P4,  or 
learn  a  great  deal  about  Pascal,  buy  these 
books,  and  save  weeks  of  your  time  bur¬ 
rowing  through  listings. 


Projects  in  Machine  Intelligence  for  Your 

Home  Computer 
By  David  L.  Heiserman 
Published  by  Tab  Books 
337  pages,  $9.95 
Reviewed  by  Richard  L.  Lozes 

A  pleasant  surprise.  The  author  was 
motivated  to  study  machine  intelligence 
by  computer  simulation  after  becoming 
frustrated  by  the  time  elapsed  in  watch¬ 
ing  a  robot  explore  its  environment.  The 


result  is  a  book  containing  insight,  peda¬ 
gogy,  and  ready-to-use  programs  that 
duplicate  his  efforts. 

The  text  expands  on  two  genera  of 
“creatures,”  Alpha  and  Beta.  These  are 
represented  by  simple  graphic  characters 
on  the  screen.  Alpha  creatures  move  at 
each  discrete  time  step  according  to  a  ran¬ 
dom  variable.  Beta  creatures  begin  life  ex¬ 
actly  like  Alpha  creatures  but,  by  contrast, 
remember  their  experiences  and  draw 
upon  those  memories  for  appropriate 
responses  to  previously  experienced  sit¬ 
uations.  The  reader  will  recognize  these 
as  examples  of  Markovian  and  non- 
Markovian  processes,  respectively. 

There  are,  further,  two  species  assoc¬ 
iated  with  each  genus,  viz.  pacifist  and 
killer.  One  can  quickly  imagine  the  com¬ 
plexity  which  communities,  especially 
integrated  communities,  of  such  creatures 
(along  with  various  “inanimate”  objects) 
might  exhibit  in  certain  phases  of  their 
life  cycle. 

The  nicest  thing  about  the  book  is 
that  the  code  (in  BASIC)  is  all  here,  ready 
to  go.  It  is  supplemented  by  clear  flow¬ 
charts.  The  reader  can  immediately  ex¬ 
plore  the  creatures,  collecting  data  along 
the  way  both  by  simple  observation  and 
with  the  aid  of  included  subroutines. 

The  tools  here  are  definitely  worth 
serious  consideration.  First,  the  concep¬ 
tual  framework  is  exceedingly  simple,  and 
fascinating  behavior  already  is  evidenced. 
Second,  because  of  the  first  point,  an 
infinity  of  variations  await  us. 

Alpha  and  Beta  creatures  only  suffer 
local  (nearest  neighbor)  interactions  with 
the  environment.  Introduction  of  various 
forms  of  action  at  a  distance  would  cer¬ 
tainly  yield  different  behavior  and  would 
likely  prompt  heated  discussion  of  top¬ 
ology. 

Beta  creatures  remember  only  the 
last  occurrence  of  a  given  situation.  Thus 
they  are  governed  by  joint  probability 
functions  of  order  two.  Why  not  three? 
or  more?  In  this  way,  a  creature’s  history 
would  more  directly  influence  its  present 
behavior. 

Forgetfulness  according  to  a  stochas¬ 
tic  function  of  time  could  simulate  effects 
which  we  are  all  familiar  with.  And  a 
stochastic  death  function  could  lead  to 
models  of  population  dynamics,  especially 
when  complemented  by  the  introduction 
of  a  new  species  —  promiscuous. 

Should  I  say  anything  negative  about 
Projects  .  .  .  ? 

No. 


A  Practical  Introduction  to  Computer 
Graphics 
By  Ian  O.  Angell 
Published  by  John  Wiley  &  Sons 
146  pages,  $16.95 
Reviewed  by  Susan  Bowers 
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A  Practical  Introduction  to  Comput¬ 
er  Graphics  explains  in  mathematical 
terms  how  to  create  graphical  representa¬ 
tions  of  complex  concepts.  It  progresses 
from  two-dimensional  graphics  and  geo¬ 
metry  to  coordinate  geometry,  three- 
dimensional  space,  and  orthographic  pro¬ 
jections.  There  is  a  chapter  on  techniques 
for  making  computer  movies,  and  one 
containing  an  interesting  list  of  suggested 
projects,  plus  a  concluding  chapter  on 
what  comes  next  in  graphics. 

This  technical  look  at  computer 
graphics  assumes  the  reader  has  a  working 
knowledge  of  Fortran  IV  and  the  mathe¬ 
matical  concepts  of  cartesian  coordinate 
geometry.  It  is  essentially  a  textbook  for 
advanced  graphics  students  who  are  also 
advanced  mathematics  students.  In  addi¬ 
tion,  it  is  very  machine-specific,  assuming 
the  use  of  “the  standard  Tektronix  4010 
scope”  and  access  to  the  Calcomp  library 
routines. 

The  book  is  very  well  written,  with 
concise  explanations  between  each  of  the 
graphics  assignments.  Assuming  that  access 
to  the  specific  equipment  and  programs  is 
necessary,  by  following  the  examples  and 
explanations,  a  student  of  advanced 
mathematics  should  be  able  to  create 
intricate  graphical  representations. 

The  machine-dependent  features 
would  tend  to  limit  the  audience  of  this 
book.  However,  the  graphics  concepts  in 
it  might  be  very  useful  in  architectural 
design  and  planning,  industrial  design, 
space  technology  design  and  futuristic 
art.  In  addition,  the  excellent  chapter  on 
techniques  for  creating  computer  movies 
could  have  application  in  educational 
films,  TV,  and  advertising. 


Word  Processing  Buyer’s  Guide 

By  Arthur  Naiman 

Published  by  BYTE  /McGraw-Hill 

325  pages,  $15.95 

Reviewed  by  D.  E.  Cortesi 

This  book  attempts  to  be  what  its 
title  suggests:  a  help  to  the  person  who  is 
shopping  for  a  word  processing  system.  In 
the  main,  it  succeeds  very  well.  Naiman 
sets  out  to  cover  four  topics.  First,  of 
course,  come  the  inevitable  chapters  on 
“What  is  a  word  processor  and  why 
should  I  want  one?”  He  conveys  the  joys 
and  advantages  of  computer-aided  writ¬ 
ing.  Then,  aided  by  many  photos,  he 
introduces  the  component  parts  of  all 
w-p  systems,  whether  they  be  dedicated 
ones  or  personal  computers.  The  orienta¬ 
tion  lessons  are  well  done;  they  should 
give  the  confused  shopper  a  good  grasp  of 
features,  terminology,  and  functional 
trade-offs. 

The  second  topic  is  how  to  evaluate 
the  software.  Naiman  devotes  a  long 
chapter  to  his  own  stringent,  detailed 


evaluation  procedure.  He  supplies  blank 
checklists  and  instructions  on  how  to  use 
them.  The  shopper  with  the  time  and 
patience  to  apply  his  procedure  in  full 
should  certainly  end  up  with  the  right 
system.  Few  people  will  have  that  much 
time  to  spare;  even  so,  just  seeing  that  an 
objective  rating  is  possible  should  be  a 
help,  and  Naiman’s  checklists  make  a 
good  basis  for  one’s  own,  shorter  version. 

Naiman’s  fourth  topic  is  the  selection 
of  hardware.  Here  again,  he  describes  all 
possible  features  at  length,  and  provides 
detailed  checklists  for  evaluation. 

No,  I  didn’t  forget  the  third  topic;  I 
saved  it  for  last  because  it’s  the  most  fun. 
Naiman  requested  input  from  70  vendors 
of  w-p  systems  (54  of  them  publishers 
of  personal  computer  software;  the  rest 
makers  of  dedicated  systems).  He  got 
responses  from  sixteen,  and  managed  to 
gather  enough  detailed  information  to 
apply  his  evaluation  procedure  to  14 
products.  These  evaluations,  with  his 
comments  and  justifications  on  the  rela¬ 
tive  point  scores,  are  the  heart  of  the 
book. 

Any  such  comparative  ranking  is 
bound  to  be  controversial.  I  looked  ahead 
to  see  where  my  own  choice  of  software 
came  in,  and  found  it  in  13th  place  out  of 
14.  Then  I  double- checked  every  step  of 
Naiman’s  procedure,  and  he  won  me  over. 

His  tests  are  comprehensive,  and  he 
has  applied  them  rigorously  and  fairly. 
Provided  that  you  allocate  points  to  fea¬ 
tures  in  the  proportions  he  does,  you  will 
come  out  with  the  same  scores.  (Two 
dedicated  systems,  CPT  and  Dictaphone, 
score  highest.  The  best-scoring  personal 
computer  package  is  Pie  Writer,  a  close 
third.  Easy  Writer  version  1.0  trails  the 
field  with  35  of  100  points.) 

Naiman  lists  90-odd  other  products, 
giving  for  each  its  vendor’s  name  and 
address,  and  adding  short  comments  for 
those  on  which  he  had  any  data.  He  notes 
InfoWorld  ratings  where  available.  And  he 
is  careful  to  note  every  product  whose 
vendor  failed  to  respond  to  his  letters  of 
inquiry.  There  is  a  hint  of  revenge  in  this, 
but  I  understand  his  frustration  very  well. 
As  Naiman  says,  “If  a  company  can’t 
answer  a  business  letter,  do  you  want  to 
depend  on  them  for  support?” 

In  summary,  I  liked  Word  Processing 
Buyer’s  Guide  very  much.  It  is  firmly  on 
the  consumer’s  side;  it  delivers  solid, 
practical  advice  in  a  clear,  informal  style; 
and  it  tells  how  (and  better,  shows  how) 
to  rate  products  objectively.  It  is  just  the 
kind  of  book  that  the  personal  computer 
industry  needs. 
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OF  INTEREST 

by  Michael  Wiesenberg 


Z80  and  80186 
in  Portable  Package 

The  Nano™  and  Pico™  series 
computers  from  SKS  Computers  are 
portables  in  real  leather  briefcases.  The 
SKS  2502  Nano™  is  compatible  with 
IBM  and  with  SKS’s  line  of  desktop 
computers.  It  has  a  Z80A,  80K  RAM, 
a  5 -by -9  built-in  green  screen  that  dis¬ 
plays  16  or  24  lines  by  80  characters, 
two  RS-232C  serial  ports,  and  two  514- 
inch,  400K  floppies.  The  software  in¬ 
cludes  CP/M,  modified  C  BASIC,  Per¬ 
fect  Writer,  Menu  Runtime,  and  Filer, 
Speller,  and  Calc.  The  package  costs 
$2495.  With  dual  processors,  adding 
the  16 -bit  Intel  80186,  Nano™  costs 
$3295,  and  has  128K  RAM.  You  can 
add  a  parallel  port  and  514-inch,  5Mb 
Winchester.  With  the  80186,  MS-DOS 
is  standard;  Oasis  and  CP/M-86  are 
options.  The  SKS  252  Pico™  is  even 
smaller,  weighing  22  pounds.  It  is  the 
same  as  the  Nano™  series,  except  that 
the  514-inch  drives  are  replaced  with 
two  314-inch,  200K  microfloppies.  How¬ 
ever,  it  is  not  compatible  with  SKS’s 
desktops.  Reader  Service  No.  105. 
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For  Altos,  More  Memory, 

More  Storage,  and  XENIX,  Too 

Altos  has  expanded  its  586  family 
of  multi-user  microcomputers,  adding 
a  model  with  514-inch  Winchester, 
40Mb,  optionally  expandable  to  80Mb. 
The  586-14  has  a  10MHz  8086,  runs 
XENIX™,  and,  like  the  present  12Mb 
(expandable  to  24Mb)  586-10,  sup¬ 
ports  both  Altos-Net  and  Ethernet 
local-area  networking.  It  also  has  3270, 
3780,  X.25,  and  SNA  protocols.  Main 
memory  is  512K,  expandable  to  1Mb 
RAM.  Standard  also  are  an  intelligent 
I/O  controller,  memory  management, 
six  serial  ports  (expandable  to  ten),  a 
battery  clock  and  calendar,  Multibus¬ 
like  architecture,  power  failure  detec¬ 
tion  (but  they  don’t  say  what  happens 
once  it  is  detected),  and  that  favorite 
buzzword  of  makers  of  business  com¬ 
puters,  internal  distributed  intelligence. 
The  586-10  costs  $7990  and  the  586- 
14,  $10,990.  Reader  Service  No.  107. 


Turn  Your  IBM  PC  Into  a  Portable 


The  Colby  PC-1  Conversion  Kit 
turns  the  IBM  PC  into  a  26-pound  port¬ 
able,  including  9-inch,  high- resolution 
display,  switching  power  supply,  wiring 
harness,  interface  boards,  and  a  sturdy 
15-by-17-by-8y2-inch  case  of  molded, 
flame-retardant  Cycolac  (the  stuff 
that  football  helmets  are  made  out  of). 
The  conversion  can  be  made  by  an 
average  user  in  less  than  one  hour,  or 


the  local  dealer  can  do  it.  After  the 
one-time  conversion,  the  PC  chassis 
can  be  used  as  an  expansion  chassis  to 
hold  up  to  five  standard  plug-in  PC 
boards,  in  addition  to  the  five  in  the 
Colby  unit.  The  Colby  PC-1  costs 
$899,  and  an  optional  battery  pack 
is  also  available  for  $489.  Reader  Ser¬ 
vice  No.  109. 


Turn  Your  Portable 
Into  a  Stationary  Unit 

While  desktop  units  are  being  con¬ 
verted  into  portables,  here  comes  the 
Data-Console  from  Professional  Data 
Systems,  a  detachable  wooden  key¬ 
board  enclosure  and  cpu/monitor 
cabinet  that  converts  the  Kaypro  into 
“a  comfortable  and  efficient  worksta¬ 
tion  in  less  than  two  minutes  without 
any  tools”  (in  other  words,  makes  it 
nonportable).  $195.  Reader  Service 
No.  111. 


Winchesters  Coming  Down 

VR  Data's  Hard  Disk  III  Subsys¬ 
tem  is  now  available  for  the  IBM  PC, 
-XT;  LNW-80,  -II;  Apple  II,  lie;  Frank¬ 
lin  Ace;  and  TRS-80  I,  and  III.  The 
disk  drive  starts  at  $995  fora  5Mb,  for¬ 
matted,  fixed  system.  Another  $150 
gets  you  an  adaptor  that  will  include 
all  hardware  and  software  to  run  the 
units.  Also  available  are  5Mb  remova¬ 
ble  disk  cartridge  systems,  and  10Mb, 
15Mb,  20Mb,  and  30Mb  configurations. 
Reader  Service  No.  113. 


Printer  Ribbons 
from  the  Drugstore? 

A  daisy  wheel  printer  for  under 
$499  is  a  definite  item  of  interest,  but 
Star  Micronics  feels  their  standard 
typewriter  ribbon  spools  are  the  big 
selling  point.  These  spools,  they  claim, 
change  the  price  of  printer  ribbons 
from  $20  to  around  $4,  and  also  elimi¬ 
nate  the  difficulty  of  finding  replace¬ 
ments.  Since  the  as-yet-unnamed 
printer  uses  Underwood-compatible 
ribbons,  the  “corner  drugstore  or  all¬ 
hours  convenience  store  may  have  it  in 
stock.”  (Perhaps  I  should  have  itali¬ 
cized  “may”;  the  7-11  near  my  house 
doesn’t  sell  typewriter  ribbons.)  Star 
Micronics  also  sells  10-  and  15Vi-inch 
dot  matrix  printers.  The  Gemini  10 
and  15,  they  say,  “offer  better  perfor¬ 
mance  than  [those]  from  the  1982 
small  computer  printer  sales  leader, 
and  at  a  significantly  lower  price.” 
(Might  they  be  referring  to  Epson?) 
At  $399  and  $649  respectively,  these 
printers  have  extra  fonts  and  larger 
built-in  buffers,  as  does  their  80- 
column  thermal  printer  —  the  $99 


STX-80.  AH  the  printers  come  stan¬ 
dard  with  removable  tractor  feeds 
and  more  adjustments  than  those  that 
(usually)  come  at  extra-cost  options, 
Reader  Service  No.  115. 


Talk  Back  to  Your  Computer 

The  newest  wrinkle  in  computer 
interfacing  comes  from  Super  Soft, 
whose  first  application  for  their  Voice- 
Drive  voice  recognition  software  is 
available  for  their  Scratchpad  financial 
spreadsheet.  For  example,  instead  of 
typing  /dc  at  the  keyboard,  you  speak 
the  words,  “now  delete  column.”  All 
commands  are  words  (in  any  language 
—  you  no  longer  have  to  remember 
which  key  does  what).  Scratchpad, 
with  VoiceDrive,  sells  for  $495  -  or, 
bundled  with  the  Tecmar  voice  recog¬ 
nition  board,  $995.  You  need  PCDOS 
and  128K  RAM.  Reader  Service  No. 
117. 


Gee  Whiz,  It’s  KeyWiz 

The  KeyWiz  VIP  (Very  Intelligent 
Peripheral)  from  Creative  Computer 
Peripherals  is  an  extra  keyboard  for 
Apple,  Ace,  and  TRS-80  Model  III 
computers.  With  62  user-programmable 
keys  (31  lower-case  and  31  shifted), 
this  keyboard  can  store  up  to  four  62- 
key  keyboards  in  its  own  static  memory, 
making  effective  248  progammable 
key  combinations,  each  holding  up  to 
eight  characters.  Custom  keyboards 
with  template  overlays  for  VisiCalc, 
Multiplan,  AppleWriter  II,  Screen- 
Writer  II,  SuperText,  Magic  Window  II, 
WordStar,  Executive  Secretary,  SVS 
Word  Handler,  PIE  Writer,  Easy  Writer, 
and  the  Model  Ill’s  Scripsit  are  now 
available.  For  an  extra  $40,  the  com¬ 
pany  will  make  you  a  customized 
plug-in  module.  The  KeyWiz  VIP  costs 
$439.  A  VisiCalc  version,  called  Key¬ 
Wiz  83,  each  of  whose  keys  holds  four 
characters,  with  numeric  keypad,  costs 
$299  (add  $40  for  word  processor 
functions).  The  KeyWiz  Convertible, 
which  also  stores  four  characters  per 
key,  costs  $299.  It  has  31  keys  and 
248  combinations,  and  comes  with 
VisiCalc  and  word  processor  functions. 
You  get  a  10-day  trial  with  a  money 
back  guarantee  and  a  full  one-year 
warranty.  Add  $8  for  p&h  for  any 
order.  Reader  Service  No.  121. 


Cheap  Bauds 

Inmac  has  a  300-baud  modem  for 
under  $130  that  only  requires  a  push¬ 
button  phone  and  modular  RJ-11  jack. 
The  unit  has  automatic  mode  selection 
from  originate  to  answer  (and  vice  ver¬ 
sa),  an  automatic  voice  or  data  switch, 
and  an  audible  carrier  detect  signal.  It 
is  compatible  with  the  Bell  103  and 
runs  on  its  own  9 -volt  battery  for  up 
to  50  hours  of  continuous  use.  Inmac 
offers  a  free  100- page  catalog  of  over 
2000  computer  accessories.  Reader 
Service  No.  123. 


CAW  for  Columnists? 

FirstDraft  from  PromptDoc  is 
computer- assisted  writing  for  CP/M 
word  processing  systems.  The  pro¬ 
gram  asks  you  what  kind  of  document 
you  wish  to  create,  and  then  questions 
you  about  the  kinds  of  ideas  you  want 
to  cover,  converting  your  thinking  into 
a  structured  outline.  From  the  outline 
it  builds  a  skeletal  document  which 
you  then  flesh  out  with  your  word 
processor.  FirstDraft  then  prompts 
you  through  the  writing  process.  When 
you’re  done,  it  automatically  generates 
a  table  of  contents  and  an  index.  The 
DocuMentor  option’s  “boilerplate” 
patterns  can  be  instantly  called  up  for 
legal  documents,  memos,  proposals, 
office  procedure  manuals,  as  well  as 
technical  and  software  manuals.  First- 
Draft  costs  $195,  DocuMentor  $295, 
and  both  together,  $395. 1  wonder  if 
they  have  a  template  for  columnists. . . 
Reader  Service  No.  125. 


Editor  Provides  Free 
Accommodations  for  Jailbird 

Actually,  that’s  not  what  the  acro¬ 
nym  EdCcmpCon  means.  It,  in  fact,  is 
the  Educational  Computing  Conference 
sponsored  by  the  IEEE  Computer 
Society  Technical  Committee  on  Com¬ 
puters  in  Education.  Uses  of  computer 
technology  in  education,  including 
CAI  (computer-aided  instruction), 
teaching  and  authoring  software  sys¬ 
tems,  touch  screens,  computergraphics, 
robotics,  total  systems  for  education, 
audio-visual  embedded  systems,  and 
languages  such  as  Logo,  Karel,  and 
Plato,  will  be  subjects  of  seminars. 
This  all  takes  place  October  18-20  at 
the  Red  Lion  Inn,  which  is  located, 
according  to  IEEE,  in  “  Silicon  Valley, 
California.”  For  those  of  you  who 
,'an’t  find  that  on  your  map,  the  Red 
Lion  Inn  is  in  San  Jose.  Registration 
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fees  will  rise  in  price  after  September 
15th.  The  fees  are:  full  conference, 
$85  ($100  after);  student  rate,  $25 
($40  after);  one-day  conference,  $45 
($55  after);  and  exhibits  only,  $10. 
You  can  get  a  buffet  lunch  for  one  day 
for  $6 ;  all  three  days,  $  15 ;  or  attend 
the  “Thursday  K-12  Banquet  Hosted 
by  Western  Region  of  College  Board” 
for  $15.  (I  put  quotation  marks  around 
that  so  you  won’t  think  it  was  me  who 
left  the  s  off  “  Board .”  And,  for  you 
non-educators,  “K-12”  means  kinder¬ 
garten  to  twelfth  grade.)  Reader  Ser¬ 
vice  No.  133. 


DEC  and  TI  Become  Polyglots 

Digital  Research  now  offers  these 
programming  languages  through  their 
CP/M  Library  for  the  DEC  Rainbow 
100  and  TI  Professional  Computer: 
Pascal/ MT+  ($600),  PL/I  ($750), 
Level  II  COBOL  ($1600),  CIS  COBOL 
($850),  CBASIC  ($325),  and  CBASIC 
compiler  ($600)  —  all  operating  under 
CP/M-86.  The  CP/M  Library  is  soft¬ 


ware  packages  for  popular  computers 
which,  up  till  now,  have  included  the 
IBM  PC,  DisplayWriter,  and  those 
using  standard  8-inch  IBM  3740  disks. 
In  addition  to  the  languages,  the  CP/M 
Library  includes:  Concurrent  CP/M-86 
for  the  PC;  CP/M-86  for  the  PC  and 
DisplayWriter;  and  the  CP/M  Card  for 
Apple  II.  The  prices  quoted  are  the 
same  as  for  those  languages  on  other 
formats.  Reader  Service  No.  127. 


Put  a  Shell  on  Your  TRS-80 

Three  of  the  best  features  of  UNIX 
are  command-line  redirection  of  stan¬ 
dard  input  and  output  during  program 
execution,  pipes  (sending  the  standard 
output  of  one  program  to  the  standard 
input  of  another),  and  multiple  entry 
of  commands  on  one  line.  ZSHELL 
from  MISOSYS  does  all  these  for  TRS- 
80  Models  I  and  III  with  LDSO  5.1, 
and  costs  $40  (plus  an  unspecified 
charge  for  shipping).  Reader  Service 
No.  129. 


What  Can  I  Say  About  This  One? 

The  CompuGift  terminal  look- 
alikes  are  a  pencil  caddy  (Computer 
Caddy),  Computer  Planter,  and  a  Com¬ 
puter  Bank.  Each  is  plastic,  4'/2-by-6- 
by-414-inch,  has  an  acrylic  screen  for 
photo,  and  comes  in  beige,  dark  grey, 
yellow,  and  magenta.  If  you  buy  in 
bulk  (for  which  you  get  a  discount), 
the  CompuGift  folks  will  even  imprint 
your  company  logo  on  the  screen. 
“The  clever  gift,”  they  say,  “for  com¬ 
puter  lovers!”  (And  lovers  of  comput¬ 
ers?)  Reader  Service  No.  131. 


I  spoke  last  time  of  the  trend  to¬ 
ward  inexpensive,  quality  home  com¬ 
puters  (the  under- $200  and  under- 
$100  variety).  Now,  Mattel  enters  the 
field  with  Aquarius,  a  4K  unit  that  can 
be  expanded  to  52K,  has  256  graphics 
characters,  displays  16  colors,  and  has 
a  keyboard  with  49  “real”  keys.  Op- 


The  Age  of  Aquarius 

tions  include  an  upper-case  and  lower¬ 
case  character  capability,  graphics 
thermal  printer,  data  recorder  for  pro¬ 
gram  storage  (sounds  like  the  Vic  20 
situation  —  you  must  use  their  re¬ 
corder),  a  “mini  expander”  unit  for 
game  cartridges,  a  LOGO  language  car¬ 
tridge,  and  several  Intellivision  games 


modified  for  the  Aquarius.  It  does 
really  seem  that  this  under- $200  com¬ 
puter  is  aimed  for  the  mass  market 
(and  not  us  tinkerer  and  programmer 
types)  because  nowhere  does  the  press 
release  mention  what  processor  it  uses! 
Reader  Service  No.  119. 
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18  Forth  and  the  Motorola  68000 

by  Joe  Barnhart 

As  68000-based  machines  proliferate,  an  increasing 
number  of  vendors  are  offering  Forth  packages  for  them. 
Speaking  from  experience,  this  author  explains  some  of 
the  considerations  involved  in  putting  Forth  on  the  68000. 

28  A  68000  Forth  Assembler 

by  Michael  A.  Perry 

Any  serious  Forth  system  should  have  a  good  assembler, 
and  68000  systems  are  certainly  no  exception.  This  writ¬ 
er  discusses  the  implementation  and  use  of  his  assembler 
along  with  some  of  the  philosophy  behind  its  design. 

44  Nondeterministic  Control  Words  in  Forth 

by  L.  L.  Odette 

Programmers  usually  expect  program  output  to  depend 
on  input  and  the  sequence  of  statements.  Making  the  pro¬ 
gram  counter  a  random  number  generator  would  appear 
to  be  disastrous;  however,  the  technique  can  be  both 
interesting  and  useful. 

54  GO  in  Forth 

by  C.  H.  Ting 

While  the  rules  for  the  game  of  Go  are  few,  putting  it  on 
a  computer  can  be  challenging.  Author  Ting  describes 
his  Forth  version:  how  it  works  and  can  be  improved. 

66  SEND  and  RCV:  A  Forth  Implementation 
of  the  XMODEM  Protocol 

by  Robert  Taylor  III 

At  the  heart  of  a  telecommunications  package  are  the 
routines  for  sending  and  receiving  files.  The  author  exam¬ 
ines  how  to  implement  Christensen’s  protocol  in  Forth. 


82  Precompiled  Forth  Modules 

by  N.  Solntseff 

Tired  of  having  to  wait  while  the  code  you  are  loading 
from  disk  compiles?  Author  Solntseff  discusses  his 
scheme  for  using  overlays  of  precompiled  Forth  code 
to  speed  up  the  process. 

86  Signed  Integer  Division 

by  Robert  L.  Smith 

The  Forth-83  Standard  adopts  the  “floored”  method  of 
integer  division.  This  look  at  the  floored  and  conven¬ 
tional  methods  illuminates  the  reasons  for  change. 

90  When  a  Page  is  Not  a  Page; 

Forth -83  and  Vocabularies 

by  George  William  Shaw  II 

The  83  Standard’s  introduction  of  vocabulary  search 
order  fell  short  of  defining  how  to  choose  the  order.  The 
author  examines  ways  and  benefits  of  utilizing  multiple 
vocabulaires  in  Forth,  including  an  experimental  propo¬ 
sal  on  specification  and  control  of  search  order. 

94  Some  Forth  Coding  Standards 

by  Edward  Wischmeyer 

Different  programming  environments  often  require  varie¬ 
ty  in  the  coding  methods  used.  Yet,  certain  fundamental 
information  must  always  be  conveyed.  The  author  exam¬ 
ines  some  of  the  factors  involved  in  expressing  your 
ideas  clearly  and  cleanly  in  Forth. 

102  The  Forth  Sort 

by  Mark  /.  Manning 

Sooner  or  later  most  programmers  need  to  sort  data.  The 
author  provides  Forth  implementations  for  three  well- 
known  sorting  methods,  as  well  as  a  program  which  allows 
timing  comparisons  under  different  data  arrangements. 


6  Editorial 
9  Letters 

12  Dr.  Dobb's  Clinic 

How  to  use  a  digital  spreadsheet  program  for  something 
fun  and  unusual:  digital  circuit  simulation. 

110  CP/M  Exchange 

More  on  disks,  drives,  and  controllers,  as  well  as  a  way  to 
tell  whether  CPU-intensive  operations  are  still  moving  or 
have  hit  a  snag. 


120  16- Bit  Software  Toolbox 

A  speed  and  accuracy  benchmark  program  for  high-level 
languages;  a  mouse  interface  for  the  IBM  PC;  informa¬ 
tion  on  IBM  and  Epson  printer  control  codes,  and  more. 

128  Of  Interest 
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EDITORIAL 


Since  our  first  special  Forth  issue  two  years  ago,  we  have  seen  enthusiasm  for  the 
language  grow  rapidly.  An  ever  increasing  number  of  people  are  discovering  the  power 
and  flexibility  that  it  offers.  This  special  issue  is  our  third  on  the  topic,  and  we  are 
delighted  with  the  amount  of  support  it  has  generated.  As  in  previous  years,  we 
received  more  good  material  than  we  could  put  into  the  issue.  We  would  like  to  thank 
all  those  who  have  contributed  their  material  and  expertise. 

We  have  tried  to  touch  upon  items  that  are  currently  important,  as  well  as  some 
things  which  should  be  generally  useful  or  fun.  While  this  issue  was  being  produced, 
the  ’83  Standard  attracted  enough  votes  for  adoption.  Two  of  the  articles  this  month 
relate  to  this  topic.  One  examines  the  change  to  floored  integer  division,  and  one 
explores  an  experimental  proposal  on  vocabularies. 

Over  the  past  year  we  have  seen  the  proliferation  of  computers  based  on  the 
Motorola  MC68000.  Vendors  have  not  been  far  behind  in  developing  Forth  systems 
for  these  new  machines,  utilizing  the  speed  and  power  that  this  processor  offers.  We 
have  therefore  included  two  68000  items  —  a  Forth  assembler  and  a  more  general 
piece  on  implementing  a  68000  Forth  system. 

The  rest  of  the  articles  should  prove  both  informative  and  entertaining,  such  as 
the  ones  on  precompiled  modules,  nondeterministic  control,  and  the  game  of  Go.  For 
non-Forth  folks,  our  departments  are  still  in  full  force  this  month  with  their  usual 
interesting  information. 


*  *  * 

You  may  also  have  noticed  that  we  have  suffered  our  first  increase  in  cover  price 
in  over  three  years.  This  became  necessary  as  the  cost  of  getting  issues  to  you  each 
month  continued  to  rise.  The  good  news  is  that  only  the  newsstand  price  has  gone  up, 
NOT  the  subscription  rate.  We  are  hopeful  that  by  this  slight  increase  we  can  continue 
to  maintain  the  high  proportion  of  editorial  material  which  we  have  brought  you  over 
the  years. 


*  *  * 

Looking  down  the  road  a  bit,  we  have  some  interesting  items  planned.  Next 
month  we  will  be  adding  a  new  bimonthly  column  which  will  focus  on  C  and  UNIX, 
as  well  as  their  derivatives  and  look-alikes.  You  will  continue  to  see  more  on  the 
68000,  programs  in  C  and  Small-C,  more  on  graphics,  and  a  few  hardware  items. 

While  we  have  some  fine  material  lined  up  for  you,  let  me  emphasize  that  we  are 
always  interested  in  new  articles  and  ideas.  To  obtain  our  writer’s  guidelines,  send  us 
an  SASE.  To  get  our  reaction  to  an  article  idea,  drop  us  a  line.  Of  course,  completed 
articles  are  always  welcome.  And  if  you  have  a  tidbit,  a  question,  or  a  discovery,  don’t 
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LETTERS 


A  Better  Algorithm  for 
Sieve  Benchmarks  in  Forth 

Dear  Sir: 

As  a  68000  Forth  vendor,  a  member 
of  the  Forth  Standards  Team,  and  as  vice 
president  of  the  Forth  Vendors  Group,  I 
have  been  asked  repeatedly  about  Forth 
performance  in  the  article  entitled  “Era¬ 
tosthenes  Sieve  Benchmarks”  (published 
in  Byte  magazine).  I  would  like  an  oppor¬ 
tunity  to  discuss  the  algorithm  supplied 
in  the  Byte  article,  introduce  a  better  al¬ 
gorithm,  provide  some  timings  for  our 
16-  and  32-bit  68000-based  products, 
and  make  some  general  comments  on  the 
Forth  approach  to  problem  solving. 

The  enclosed  Forth  code  contains 
three  versions  of  the  Eratosthenes  Sieve 
Benchmark  as  published  in  Byte  magazine. 

The  first  version  (shown  in  Figure  1, 
below)  represents  the  original  coding 
from  the  article  (including  a  corrected 
typo).  With  CSFs  68000  Multi-Forth  on 
an  HP  Series  200  model  26,  10  passes 
execute  in  22.98  seconds  (16-bit  version) 
and  25.77  seconds  (32-bit  version). 

Unfortunately  (or  fortunately  de¬ 
pending  on  your  viewpoint),  this  algorithm 
can  be  better  written  in  Forth.  A  better 
algorithm,  similar  to  those  optimized  for 


C  and  Pascal,  is  shown  in  Figure  2  (be¬ 
low). 

Note  that  the  BEGIN  .  .  .  WHILE  . .  . 
REPEAT  structure  in  the  former  has  been 
replaced  by  a  DO  .  .  .  +LOOP  structure  in 
the  latter,  taking  advantage  of  Forth’s 
ability  to  use  loop  indices  as  addresses. 

This  algorithm  runs  10  passes  in 
15.62  seconds  (16-bit  version)  and  17.35 
seconds  (32 -bit  version). 

In  the  unlikely  event  that  an  applica¬ 
tion  would  ever  require  the  rapid  compu¬ 
tation  of  the  first  1899  prime  numbers, 
the  tightest  loop  would  normally  be  re¬ 
duced  to  code  using  the  in-line  assembler. 

The  68000  code  sequence  in  Figure 
3  (below)  replaces  the  internal  loop, 
which  traverses  the  flags  array  clearing 
flags  for  multiples  of  known  prime 
numbers. 

Note  that  this  code  procedure  re¬ 
places  six  high-level  words  with  eight 
assembly  instructions  and  utilizes  the 
BEGIN  .  .  .  UNTIL  control  structure 
within  the  assembler. 

This  results  in  the  final  rendition 
shown  in  Figure  4  (below),  which  exe¬ 
cutes  in  8.86  seconds  (16-bit  version) 
and  9.81  seconds  (32 -bit  version). 

Industry  experience  suggests  that 


10%  of  the  code  in  a  typical  application 
executes  90%  of  the  time  (our  experience 
in  real  time  systems  suggests  that  this  is 
closer  to  5%  and  95%).  The  current  trend 
in  other  languages  is  toward  large  multi¬ 
pass  optimizing  compilers  which  optimize 
the  entire  program  in  an  attempt  to  catch 
the  10%  of  the  code  that  is  in  fact  worth 
the  effort. 

Forth,  however,  encourages  a  differ¬ 
ent  approach.  All  code  is  typically  writ¬ 
ten  and  debugged  in  high  level.  Then,  if 
necessary,  time  critical  words  are  recoded 
with  the  in-line  assembler. 

Forth  naturally  factors  applications 
into  a  hierarchical  set  of  simple  functions 
(typically  under  7  operators  or  operations 
per  function).  These  functions  pass 
operands  via  the  stack.  Recoding  specific 
words  with  the  in-line  assembler,  as  we 
have  seen  in  the  examples,  is  a  very 
straightforward  process. 

The  10%  faster  execution  time  of  the 
16-bit  product  is  typical  for  most  applica¬ 
tions,  and  due  to  the  fewer  memory 
fetches  required  to  handle  16 -bit  versus 
32-bit  stack  items.  Although  the  16-bit 
version  complies  with  the  79  Standard, 
10%  performance  is  a  small  price  to  pay 
in  consideration  of  the  facts  that:  the 


(  SIEVE  ) 

8192  CONSTANT  SIZE 
VARIABLE  FLAGS  SIZE  ALLOT 

:  DO-PRIME 

FLAGS  SIZE  1  FILL  (  SET  ARRAY  ) 

0  (  0  COUNT  )  SIZE  0 
DO  FLAGS  I  +  C@ 

IF  I  DUP  +  3  +  DUP  I  + 

BEGIN  DUP  SIZE  < 

WHILE  0  OVER  FLAGS  +  Cl  OVER  +  REPEAT 
DROP  DROP  1+ 

THEN 

LOOP 

.  PRIMES"  ; 

:  10-TIMES  CR  ?RTC  10  0  DO  DO-PRIME  LOOP  .MS  ; 

Figure  1 . 


(  SIEVE  BENCHMARK  IMPROVED  ALGORYTHM  ) 

:  DO-PRIME. HI  (  —  FASTER  ALGORITHM  IN  HIGH  LEVEL  ) 
FLAGS  SIZE  01  FILL 

0  (  PRIME  COUNTER  )  SIZE  0  (  RANGE  ) 

DO  I  FLAGS  +  C@  (  PRIME  ?  ) 

IF  3  I  +  I  +  DUP  I  +  SIZE  < 

IF  SIZE  FLAGS  +  OVER  I  +  FLAGS  + 

DO  0  I  C!  DUP  +  LOOP 

(FLICK  DOWN  MODULO  I  FLAGS) 

THEN  DROP  1+  (  BUMP  PRIME  COUNTER  ) 

THEN 

LOOP  .  PRIMES"  ; 

:  10-TIMES. HI  CR  ?RTC  10  0  DO  DO-PRIME. HI  LOOP  .MS  ; 


Figure  2. 


(  CODE  ROUTINE  FOR  SIEVE  ) 

CODE  FLICK' EM  (  PRIME! \ LIM ITVSTART  --  PRIME!  ) 

(  REPLACES:  DO  0  I  C!  DUP  +L00P  ) 

SP  )+  A1  LONG  MOVE,  SP  ) +  D1  LONG  MOVE, 

SP  ()  D0  LONG  MOVE,  0  D2  MOVEQ , 

BEGIN,  D2  A1  ()  BYTE  MOVE,  DO  A1  LONG  ADDA, 

A1  D1  LONG  CMP,  LT  UNTIL, 

NEXT  END-CODE 


Figure  3. 


(  SIEVE  BENCHMARK  —  TYPICAL  SOLUTION  ) 

:  DO-PRIME. LO 

(  —  FASTER  ALGORITHM  WITH  CODE  PROCEDURE) 

FLAGS  SIZE  01  FILL 

0  (  PRIME  COUNTER  )  SIZE  0  (  RANGE  ) 

DO  I  FLAGS  +  C@ 

IF  3  I  +  I  +  DUP  I  +  SIZE  < 

IF  SIZE  FLAGS  +  OVER  I  +  FLAGS  + 

FLICK’ EM  (FLICK  DOWN  MODULO  I  FLAGS  ) 
THEN  DROP  1+  (BUMP  PRIME  COUNTER) 

THEN 

LOOP  .  ."  PRIMES"  ; 

:  10-TIMES. LO  CR  ?RTC  10  0  DO  D0-PRIME . LO  LOOP  .MS  ; 


Figure  4. 
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32-bit  system  allows  unlimited  program 
size;  most  delivered  68000  hardware  is 
shipped  with  more  than  64K  available; 
and  the  phone  company  is  now  selling 
25 6K  RAM  parts. 

In  summary,  a  better  Sieve  imple¬ 
mentation  in  Forth  provides  a  33%  speed 
improvement,  while  coding  the  tightest 
loop  in  assembly  contributes  another 
fifty  to  sixty  percent.  One  cannot  fault 
the  authors  of  the  article;  they  openly 
acknowledge  far  greater  proficiency  in  C 
and  Pascal.  It  does  illustrate,  however,  the 
significant  impact  of  programmer  profi¬ 
ciency  in  the  language  under  test  on  tim¬ 
ing  comparisons  in  benchmarks. 

I  appreciate  the  opportunity  to  ex¬ 
press  these  views  to  your  readership,  and, 
as  a  member  of  the  Forth  community, 
stand  up  and  applaud  DDJ’s  continuing 
involvement  in  Forth. 

Sincerely, 

Don  Colburn,  President 
Creative  Solutions,  Inc. 

Vice  President 
Forth  Vendors  Group 

Forth  Debugging  from 
a  Full-Screen  Editor 

Dear  DDJ, 

One  of  the  problems  with  most  de¬ 
bugging  aids  is  that  you  must  continually 
look  back  and  forth  between  a  listing  of 
the  program  and  the  screen  to  keep  track 
of  where  you  are.  This  program,  however, 
will  add  single-step  capability  to  the 
Laxen  full-screen  editor  (Dr.  Dobb’s 
Journal,  Sept.  1981,  page  27)  so  that  the 
cursor  pops  from  word  to  word  as  the 
program  is  executed  one  step  at  a  time. 
The  parameter  stack  contents  are  dumped 
to  the  bottom  of  the  screen  with  each 
program  step. 

If  a  bug  is  found  while  stepping 
through  the  program,  you  can  make  im¬ 
mediate  changes  since  you  are  still  in  the 
editor  with  the  cursor  positioned  at  the 
offending  word.  After  making  a  change 
you  can  immediately  resume  debugging. 


The  new  function  is  installed  by  sim¬ 
ply  loading  screen  98  (Figure  1,  below) 
just  before  screen  80  in  the  Laxen  editor. 
Screen  80  contains  the  CASE:  statement, 
which  assigns  control  key  functions.  To 
assign  the  STEP  function  to  control-W, 
simply  replace  the  BEEP  just  after 
INSERT-MODE  in  that  CASE:  statement 
with  STEP. 

Pressing  control-W  will  now  cause 
the  word  (or  number  at  the  cursor)  to  be 
interpreted  as  though  it  had  been  entered 
at  the  keyboard  and  followed  by  a  car¬ 
riage  return.  The  parameter  stack  will  be 
dumped  to  the  bottom  of  the  screen,  and 
the  cursor  will  move  right  to  the  next 
word. 

Comments  and  compile-only  words 
can  be  skipped  over  by  using  the  normal 
cursor  control  keys.  Normally,  input 
parameters  should  be  put  on  the  stack 
just  before  calling  the  editor. 

The  ’79  Standard,  MVP  Forth  system 
was  used  with  the  Laxen  editor,  but  the 
same  technique  can  be  applied  to  any 
full-screen  editor. 

Sincerely, 

Tom  Blakeslee 
Orion  Instruments 
172  Otis  Avenue 
Woodside,  CA  94062 

In  Defense  of  CP/M  Plus 

In  his  June  Clinic,  Dave  Cortesi  noted 
some  weaknesses  in  CP/M  Plus’s  sector 
buffering  scheme.  Last  month,  the  In¬ 
tern’s  direct -access  I/O  benchmarks  pro¬ 
duced  a  much  more  favorable  picture. 
Below  is  a  response  to  the  June  Clinic 
on  behalf  of  Digital  Research  which,  un¬ 
fortunately,  was  received  too  late  to  be 
included  in  the  August  issue.  While  the 
discussion  will  have  some  overlap  with 
the  August  Clinic,  it  is  still  enlightening. 
-  Ed. 

Dear  Sir: 

Digital  Research  invited  me  to  re¬ 


spond  to  the  CP/M  Plus  review  that 
appeared  in  the  June  Dr.  Dobb’s  Clinic 
column  written  by  David  E.  Cortesi.  I  was 
not  involved  with  the  design  or  imple¬ 
mentation  of  CP/M  Plus,  so  DRI  felt  my 
reaction  to  the  article  would  be  objective. 

The  column  suggests  that  DRI  over¬ 
looked  several  obvious  ways  to  speed  up 
disk  accesses,  and  may  have  misrepre¬ 
sented  or  incorrectly  documented  their 
product.  I  was  quite  impressed  by  the 
detective  work  Mr.  Cortesi  performed  to 
learn  what  goes  on  inside  CP/M  Plus,  but 
I  think  his  conclusions  are  incorrect.  Let 
me  respond  first  to  some  specific  claims 
made  in  the  column,  and  then  address  the 
general  question  of  operating  system  opti¬ 
mization. 

The  column  reported  some  trouble  in 
using  the  MOVE  and  XMOVE  functions 
to  examine  internal  operating  system  data 
structures.  Had  Mr.  Cortesi’s  SHOWBCB 
program  “played  by  the  rules”  of  CP/M 
Plus,  however,  it  would  not  have  been 
swapping  memory  banks.  CP/M  applica¬ 
tion  programs,  by  definition,  execute 
only  within  the  context  of  Bank  1.  CP/M 
Plus  does  leave  the  overly  clever  program¬ 
mer  many  opportunities  to  screw  up,  as 
did  CP/M  2.2.  Remember,  though,  that 
the  BIOS  exists  to  serve  the  BDOS,  so 
direct  I/O  calls  can  (and  sometimes  do) 
interfere  with  higher-level  OS  functions. 

The  column  “discovers”  some  things 
that  had  already  been  spelled  out  in  Digi¬ 
tal  Research  documentation  and  articles, 
like  the  fact  that  CP/M  Plus  does  not  ac¬ 
tually  perform  least -recently  used  (LRU) 
sector  buffering  during  sequential  file 
I/O.  A  DRI  article  that  introduced  CP/M 
Plus  in  the  May  1983  issue  of  Computer 
Design  explains  why:  “However,  the 
operating  system  overrides  the  LRU 
scheme  if  a  series  of  sequential  sectors  are 
referenced.  This  avoids  wiping  clean  the 
entire  buffer  area.”  The  number  of  buffers 
consumed  for  each  of  the  experiments 
described  is  consistent  with  this  fact. 

The  column  states  that  in  developing 
software,  “the  file  one  program  writes, 
another  program  is  going  to  read.”  A 
single  source  file,  in  turn,  may  be  edited, 
assembled,  linked,  and  listed.  In  non¬ 
trivial  programs,  however,  changes  often 
affect  several  source  modules,  and  each 
module  may  need  re-editing  as  typing 
errors  are  detected.  Some  translators 
produce  a  number  of  intermediate  and 
output  files.  In  practice  it’s  not  at  all 
clear  which  files  should  be  retained  by 
the  OS  for  ensuing  programs  to  use. 

Also,  software  development  is  not 
actually  a  typical  CP/M  application. 
Mr.  Cortesi  and  I  (and  probably  most  of 
your  readers)  do  spend  much  of  our  time 
writing  new  programs,  but  most  CP/M 
machines  are  used  primarily  to  run  spel¬ 
ling  checkers,  data  base  systems,  and 

(Continued  on  page  132) 


SCR 

#98 

0 

(  EDITOR  DEBUG, 

STEP) 

1 

:  STEP  (  — >  (  LOADS  ONE  WORD  &  DISPLAYS  STACK) 

£ 

BUFPOS  DUP 

(  START  ADR  OF  WORD) 

R-WORD  ( 

MOVE  CURSOR  RIGHT  1  WORD) 

4 

BUFPOS  SWAP 

-  50  MIN  1-  <  LENGTH) 

DUP  TIB  @  + 

0  SWAP  1  (  NULLS  TO  END  STREAM) 

6 

TIB  @  SWAP 

BMOVE  (  MOVE  WORD  TO  TIB) 

7 

0  18  CRTXY 

(  MESSAGES  ON  LOWER  SCREEN) 

8 

BLK  @  ) R 

0  BLK  1  (  SAVE  &  SEL  TERM  INPUT) 

9 

> IN  0  >  R 

0  >  IN  ! 

A 

INTERPRET 

B 

40  SPACES 

(  CLEAR  LINE  FOR  STACK  DISPLAY) 

C 

0  17  CRTXY 

. S  (  SHOW  STACK) 

D 

R>  > IN  ! 

R>  BLK  !  (  RESTORE) 

E 

F 

0  MOVE-CURSOR  (  RESTORE  CURSOR  POSITION)  ; 

Figure  1. 
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by  D.  E.  Cortesi,  Resident  Intern 


The  Digital  Spreadsheet 

Despite  all  the  software  available 
these  days,  it’s  still  the  spreadsheet  calcu¬ 
lator  that  most  exemplifies  the  helpful, 
responsive,  intimate  nature  of  a  personal 
computer.  Once  you’ve  owned  a  Visi-, 
Perfect-,  Multi-,  or  Super-Calc,  you  never 
want  to  be  without  it  again. 

What’s  more,  new  uses  for  the  damn 
things  keep  turning  up.  We’ve  been  play¬ 
ing  around  with  one  that  was  new  to  us, 
and  might  be  to  you  as  well. 

We  picked  this  idea  out  of  the  letters 
column  of  a  recent  issue  of  Byte.  A  previ¬ 
ous  issue  had  carried  a  rather  nice  digital - 
logic  simulator  program  written  in  BASIC. 
The  letter-writer  casually  pointed  out, 
with  no  details,  that  you  don’t  need  any 
special-purpose  software;  it  is  just  as  easy 
to  simulate  digital  logic  with  a  spread¬ 
sheet  calculator. 

You  don’t?  It  is?  Hmmm.  Wonder 
what  he  means?  So  we  started  playing 
around  with  our  well-worn  copy  of  Super- 
Calc,m,  and  darned  if  he  wasn’t  right. 
What’s  more,  it’s  great  fun,  and  might 
even  have  a  practical  use. 

Simple  Gates 

The  obvious  first  thing  to  try  was  the 
simulation  of  the  five  simple  gates:  the 
And,  Nand,  Or,  Nor,  and  Xor  circuits. 
And  they  turn  out  to  be  easy,  at  least 
with  SuperCalc  version  1.4  (the  exact 
product  and  version  may  be  important  to 
this;  we  have  no  idea  if  other  spreadsheets 
will  support  the  expressions  shown  here). 

Provided  that  you  limit  all  values  to 
being  either  0  or  1,  an  And  gate  is  simply 
a  cell  containing 

inputl  *  input2 

where  inputl  and  input2  are  the  names  of 
other  cells.  (We  will  use  this  convention 
throughout;  an  italicized  name  represents 
a  reference  to  a  spreadsheet  cell.)  If  either 
input  cell  contains  0,  the  value  of  the 
And-cell  is  0;  if  both  contain  1,  its  value 
is  1 . 

An  Or  gate  is  trickier.  The  simple 
expression 

inputl  +  input2 

works,  in  that  its  value  is  nonzero  if 
either  input  is  nonzero,  but  when  both 
inputs  are  nonzero,  its  value  exceeds  1 . 
Fortunately,  SuperCalc  follows  BASIC  in 
that  the  value  of  a  relational  expression  is 
a  number,  0  for  false  and  1  for  true.  So 
an  Or  gate  becomes 

0  <  ( inputl  +  input 2  ) 


which  has  the  value  0  only  when  both 
inputs  are  0,  and  the  value  1  otherwise. 
We  recast  our  standard  And  to  the  same 
format,  just  in  case  some  floating-point 
near- zero  should  creep  into  a  simulation: 

0  <  ( inputl  *  input2) 

The  negated  forms  Nand  and  Nor  fall 
out  of  this  very  nicely,  just  by  changing 
the  relational  function  from  less- than  to 
equals.  Here  are  all  four  gates: 

And:  0  <  ( inputl  *  input2 ) 

Nand:  0  =  ( inputl  *  input2 ) 

Or:  0  <  ( inputl  +  input2) 

Nor:  0  =  ( inputl  +  input2 ) 

They  are  easily  extended  to  more  inputs. 
An  Xor  gate  is  simply  the  not-equals 
relationship: 

Xor:  inputl  <>  input2 

One  beauty  of  a  spreadsheet  is  the 
ease  of  building  a  truth-table  for  one-cell 
functions  like  these.  Assign  a  row  to  each 
input,  with  an  appropriate  label  in  column 
A,  and  enter  all  combinations  of  constant 
values: 

Input  A:  0  0  1  1 
Input  B :  0  1  0  1 

Enter  the  function  expression  in  the  third 
row,  supplying  the  names  of  the  cells 
above  it  for  its  input  values.  Then  replicate 
the  expression,  with  automatic  adjust¬ 
ment  of  references,  across  the  row.  Voila. 
a  truth  table  (and  instant  insight  for  a 
student  in  a  lab). 

Having  a  supply  of  gates  in  hand,  we 
wanted  to  build  some  circuits.  We  don’t 
do  that  much  hardware  hacking,  so  we 
hauled  down  a  dog-eared  copy  of  Don 
Lancaster’s  TTL  Cookbook  (Howard  W. 
Sams,  1979)  and  searched  it  for  ideas. 
The  first  one  we  tried  was  the  Set -Reset 
flipflop,  composed  of  two  Nand  gates 
(p.  162).  It  looks  like  this,  with  labels  in 
the  first  column  and  expressions  in  the 
second: 

not-S:  1 
not-R:  1 

Q:  0  =  ( not-S  *  not-Q) 

not-Q:  0  =  ( not-R  *  Q) 

The  feedback  reference,  or  self-reference, 
or  circular  reference  that  is  going  on  be¬ 
tween  the  Q  and  not-Q  cells,  is  usually  a 
no-no  in  spreadsheet  work.  If  your  calcu¬ 
lator  rejects  these  expressions,  you  are 
out  of  luck  for  the  rest  of  this  column. 
SuperCalc  1.4  accepts  them  without  com¬ 
plaint. 


It  helps,  when  operating  the  S/R  flip- 
flop,  to  turn  off  automatic  recalculation. 
The  manual  signal  for  a  recalc  (usually 
the  exclamation- mark  key)  then  initiates 
one  cycle  of  the  digital  simulation.  Set 
the  not-S  line  low  by  entering  a  constant 
0  into  its  cell.  Recalc;  the  Q  cell  should 
go  high.  Set  not-S  high  and  recalc;  Q 
should  remain  high.  Set  not-R  low  and 
recalc;  the  flipflop  should  flip  (flop?), 
making  not-Q  high  and  Q  low.  Set  not-R 
high  again  and  recalc;  the  outputs  should 
hold  their  state.  And  so  on. 

Making  a  Clock 

The  interesting  gates  are  clocked  cir¬ 
cuits,  so  we  wanted  an  oscillator  expres¬ 
sion:  a  cell  that  would  alternate  between 
0  and  1  on  each  recalc.  Without  it,  we 
would  have  to  enter  each  clock  state 
manually.  We  fiddled  around  for  a  while, 
and  finally  found  that  the  simplest  kind 
of  oscillator  was  the  naked  self-reference. 
At  least  with  SuperCalc,  if  you  put  into 
cell  A 1  the  expression 

NOT(Al) 

you  have  an  oscillator.  It  changes  state, 
from  0  to  1  or  back,  each  time  the  sheet 
is  recalculated.  From  here  on,  references 
to  clock  are  references  to  such  an  oscil¬ 
lator  cell.  We  found  it  best  to  have  just 
one  oscillator  on  a  sheet,  and  to  refer  to 
its  cell  wherever  the  clock  signal  was 
needed.  It  was  beginning  to  dawn  on  us 
that,  in  a  spreadsheet  Digital  Simulator, 
a  cell  reference  was  the  equivalent  of  a 
wire  in  the  real  circuit. 

Clocked  Flipflops 

Now  we  had  a  clock,  we  could  make 
a  Clocked  S/R  flipflop  (see  Lancaster, 
page  191).  It  looks  like  this: 

not -set:  1 
not-clr:  1 
elk -in:  clock 

elk-set:  0  =  ( not-set  *  elk-in) 
clk-clr:  0  =  (not-clr  *  elk-in) 

Q:  0  =  ( elk-set  *  not-Q) 

not-Q:  0  =  ( clk-clr  *  Q) 

This  circuit  is  operated  much  like  the  un¬ 
clocked  one.  You  set  a  low  level  (constant 
zero)  in  the  not-set  or  not-clr  cell  when 
the  clock  is  low,  and  recalc.  Then  set  a 
high  level  (constant  one)  and  recalc  again. 
To  enter  a  constant  and  then  recalc  is  to 
simulate  applying  a  signal  precisely  on  the 
leading  or  trailing  edge  of  the  clock  —  on 
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the  leading  edge  if  the  clock  is  now  0  and 
going  to  1,  on  the  trailing  edge  if  the 
clock  is  now  1  and  going  to  0. 

Moving  to  the  Chip  Level 

We  went  on  to  build  a  Master-Slave 
flipflop  and  a  few  other  circuits  out  of 
basic  gates,  but  it  was  beginning  to  get 
tedious.  The  difficulty  comes  from  the 
complex  mental  transformations  that 
must  be  made  between  gates  on  a  sche¬ 
matic  and  the  arbitrary  row  and  column 
addresses  of  the  spreadsheet.  It’s  not 
difficult  to  remember  that  clock  is  Al, 
but  when  you  have  half-entered  a  circuit 
of  as  few  as  eight  gates,  it  becomes  very 
difficult  to  keep  track  of  what  gate  is  in 
what  cell.  It  helps  to  enter  lots  of  labels, 
as  indicated  in  the  examples  here,  but  it’s 
still  easy  to  miswire  the  simulation,  and 
hard  to  debug  it  once  you  have. 

The  named-references  and  relative- 
references  supported  by  MultiPlantm 
would  have  been  a  great  help,  but  we 
didn’t  have  MultiPlan;  we  had  SuperCalc 
1.4,  which  is  only  slightly  smarter  than 
original  VisiCalc.  So  we  tried  a  different 
approach. 

To  this  point  we  have  used  the  spread¬ 
sheet  to  simulate  a  patchboard  and  ex¬ 
pressions  to  simulate  gates.  But  nowadays, 
nobody  designs  with  gates;  they  design 
with  chips.  So  why  not  use  the  spread¬ 
sheet  to  simulate  a  wire-wrap  circuit 
board,  and  build  simulated  chips?  We 
decided  to  set  up  a  spreadsheet  template 
for  each  common  chip.  Take,  for  instance, 
the  template  for  a  7400  Quad  2-input 
Nand: 


7400 . 

■-  - 

1.  A 

1 

2:  B 

1 

3:  -A  *  B 

0  =  (A  * B ) 

4:  C 

1 

5:  D 

1 

6:  -C  *  D 

0  =  {C*  B) 

9:  E 

1 

10:  F 

1 

8:  -E  *  F 

0  =  (E*  F) 

12:  G 

1 

13:  H 

1 

11:  -G  *  H 

0 =(G*H) 

The  chip  is  represented  by  a  rectangular 

patch  of  the  worksheet,  two  columns 
wide  and  with  as  many  rows  as  it  has  sig¬ 
nal  pins.  The  left-hand  column  contains 
labels  that  document  the  pin  numbers 
and  their  uses;  the  pins  are  given  in  logi¬ 
cal,  not  numeric,  order.  The  right-hand 
column  contains  the  expressions  that  im¬ 
plement  the  functions  of  the  chip.  Input 
pins  are  entered  with  constant  values 
(usually  1,  since  TTL  inputs  float  high). 

The  idea  is  to  copy  the  chip -patch  to 
wherever  on  the  sheet  a  chip  of  this  kind 
is  needed.  Then  you  “wire  it  up”  by  en¬ 


tering  cell  references  into  its  input-pin 
cells  and  entering  the  names  of  its  output- 
pin  cells  into  the  inputs  of  other  chip- 
patches. 

Enter  the  IF 

A  fine  idea,  we  thought,  until  we 
advanced  beyond  the  level  of  the  7400, 
7402,  etc.,  to  more  elaborate  things  like 
a  7474  dual  D-type  latch.  It  obviously 
Wouldn’t  be  handy  to  incorporate  two 
gate-level  simulations  of  D-type  latches 
into  the  simulation  of  the  chip.  First,  it 
would  make  the  chip  template  too  bulky, 
and  second,  it  would  add  too  many  cells 
to  what  should  be  an  elementary  function 
(SuperCalc  was  already  slowing  down 
quite  noticeably).  We  wanted  to  keep  the 
one-row-per-pin  relationship  in  each 
chip  template.  Therefore,  we  wanted  a 
one-cell  expression  that  would  simulate 
all  the  functions  of  a  D-type  latch. 

We  worked  out  such  an  expression  on 
paper,  based  on  SuperCalc’s  IF  function. 
The  IF  function  has  a  form  reminiscent 
of  LISP: 

IF  (  predicate,  true,  false  ) 

The  calculator  evaluates  the  expression 
predicate.  If  its  value  is  nonzero,  the  val¬ 
ue  of  expression  true  becomes  the  value 
of  the  cell;  if  zero,  the  value  of  false. 

Here  is  how  the  D-type  latch  is  sup¬ 
posed  to  work  (condensed  from  Lancas¬ 
ter,  page  197): 

(1)  If  the  D  input  is  positive,  the  Q  out¬ 
put  goes  or  stays  positive  when  the 
clock  goes  positive. 

(2)  If  the  D  input  is  grounded,  the  Q 
output  goes  or  stays  grounded  when 
the  clock  goes  positive. 

(3)  If  the  Preset  and  Clear  inputs  are 
both  positive,  they  do  not  interfere 
with  the  clocked  operations. 

(4)  If  the  Preset  input  is  grounded,  the 
flipflop  immediately  goes  to  a  state 
with  not-Q  grounded  and  Q  positive. 

(5)  If  the  Clear  input  is  grounded,  the 
flipflop  immediately  goes  to  a  state 
with  not-Q  positive  and  Q  grounded. 

And  here  is  how  we  stated  those  rules 
using  nested  IF  functions  (with  pretty¬ 
printing  here  for  clarity): 

IF (  NOT( preset),  1, 

IF  (  NOT  (  clear),  0, 

IF (  clock,  D,  self  ))) 

The  reference  to  self  is  a  reference  to  the 
cell  that  contains  that  whole  humongous 
expression. 

We  had  severe  doubts  as  to  whether 
SuperCalc  could  handle  a  triply  nested, 
self- referential  IF  function,  but  it  did. 
The  resulting  7474  template  looks  like 
this: 

7474 . 

1:  a,clr  1 

2:  a,D  1 


3:  a, elk 

clock 

4:  a, set 

1 

5:  a,+Q 

(the  big  IF  function) 

6:  a, -Q 

NOT  (pin  5  ) 

13:  b.clr 

1 

12:  b,D 

1 

11:  b.clk 

clock 

10:  b,set 

1 

9:  b,+Q 

(again,  the  big  IF) 

8:  b, -Q 

NOT  (pin  9 ) 

We  then  subjected  SuperCalc  to  an 
even  sterner  test:  the  simulation  of  a  JK- 
type  latch.  Look  up  the  rules  for  that  one 
yourself;  here  is  an  IF  that  implements  it: 

IF(  NOT(jer),  1, 

IF (  NOT(ctear),  0, 

IF(  clock,  self, 

I F (  J  <>  K,  J, 

IF  (  J,  NOT  (self),  self  ))))) 

This  is  not  the  kind  of  expression  that 
turns  up  in  financial  modeling,  so  we 
wouldn’t  have  been  surprised  had  Super¬ 
Calc  tripped  over  it.  However,  it  worked 
just  fine.  Here’s  a  tip  of  the  Intern’s  sterile 
cap  to  Sorcim  for  not  building  any  arbi¬ 
trary  limits  into  their  product. 

We  haven’t  put  any  of  this  to  practi¬ 
cal  use,  but  perhaps  a  reader  can.  Even  if 
it  doesn’t  turn  out  to  be  useful  for  real 
design  work,  it  is  certainly  a  grand  educa¬ 
tional  tool.  It’s  also  fun  to  play  with. 
Here  are  some  problems  that  we  have 
considered,  but  not  solved. 

The  most  complicated  chip  for  which 
we’ve  built  a  template  is  the  74164  8 -bit 
shift  register.  That  one  needed  two  col¬ 
umns  of  expressions.  One  column  picked 
up  and  shifted  the  current  outputs  on  the 
trailing  edge  of  the  clock;  the  other  col¬ 
umn  delivered  the  new  outputs  on  the 
leading  edge.  It’s  tricky  getting  both  col¬ 
umns  to  reset  properly.  Can  you  do  it? 
What  about  other  chips,  like  decade 
counters,  l-of-8  distributors,  compara¬ 
tors,  and  parity  generators?  Can  they  be 
modeled  as  spreadsheet  templates? 

More  advanced  logic  circuits  need  a 
multiphase  clock,  in  which  the  master 
oscillator’s  beat  is  divided  into  phases 
(like  the  T  states  of  an  8080).  Can  you 
devise  an  arrangement  of  cells  to  yield 
a  four-phase  clock  cycle?  Its  heart  would 
be  our  simple  oscillator,  but  its  outputs 
would  be  TO,  Tl,  T2,  and  T3.  It  ought 
also  to  have  a  numeric  display  so  the 
operator  could  easily  see  what  phase  it 
was  in,  and  some  kind  of  instant  reset  to 
the  just-before-TO  state.  Maybe  there’s  a 
standard  chip  for  this  that  you  could 
model. 

Then  there’s  the  problem  of  handling 
address  and  data  busses.  If  the  simulator 
is  to  be  easy  to  operate,  it  should  be  pos¬ 
sible  to  enter  a  16-bit  address  or  an  eight- 
bit  byte,  as  a  number,  to  a  single  cell, 
with  its  binary  values  then  somehow  dis¬ 
tributed  automatically  over  eight  or  six- 
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teen  simulated  bus  lines.  Conversely,  it 
would  be  nice  to  have  a  simulated  LED 
display  cell  that  would  show  the  value  of 
eight  binary  output  cells  as  a  single  value. 
These  problems  (especially  the  problem 
of  decimal-to-hex  display)  may  not  be 
soluble  with  a  general-purpose  spread¬ 
sheet  calculator. 

The  spreadsheet  calculator  imposes  a 
particular  order  of  calculation.  What,  if 
anything,  is  the  relationship  between  that 
and  propagation  delay  in  the  simulated 
circuit?  Can  order  of  calculation  be  made 
useful  in  the  simulation?  Does  it  impose 
constraints  on  the  realism  of  the  simula¬ 
tion? 

Actually,  if  you  were  to  solve  all 
these  problems,  you  would  have  the  basis 
of  a  nice  software  product.  If  you  market 
such,  don’t  forget  to  give  credit  where  it’s 
due.  Have  fun,  and  keep  those  cards  and 
letters  coming. 


Forth  and  the 
Motorola  68000 


One  of  the  most  powerful  micro¬ 
processors  available,  the  Motorola 
68000  has  an  architecture  that 
lends  itself  to  fast,  efficient,  “threaded” 
languages  such  as  Forth.  If  you  have  an 
interest  in  the  inner  workings  of  the  MC¬ 
68000  processor  or  are  interested  in  the 
heart  of  a  threaded  interpretive  language 
—  the  “inner”  or  “address”  interpreter  — 
then  read  on. 

Although  classed  as  a  16-bit  micro¬ 
processor,  the  MC68000  maintains  full 
32-bit  registers  for  all  address  and  data 
information.1  With  its  24  bits  of  address¬ 
ing  range,  the  processor  can  directly  access 
up  to  16Mb  of  main  memory  without 
need  of  segmentation  or  bank -switching 
schemes.  But  the  most  useful  feature  of 
the  MC68000  (for  Forth  designers)  is  its 
rich  set  of  addressing  modes  and  its  regu¬ 
lar  (or  consistent)  instruction  set.  It 
supports  14  different  addressing  modes, 
including  the  all-important  “indirect 
with  auto -increment”  mode  (which  is 
vital  to  a  threaded  language). 

Any  threaded  interpretive  language 
can  unlock  the  power  of  the  MC68000 
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processor,  but  Forth  has  characteristics 
that  make  it  the  ideal  choice  for  the  lan¬ 
guage  designer.  Most  of  all,  its  popularity 
assures  a  steady  supply  of  programs  that 
can  be  adapted,  with  minimal  effort,  to 
the  new  hardware. 

Not  all  Forths  are  the  same,  though, 
and  differences  that  appear  subtle  from 
the  outside  can  have  profound  effects  on 
the  overall  performance  of  the  language. 
One  such  difference  is  the  choice  of 
address  interpreter:  whether  direct  or 
indirect  threaded  code  is  used?  The  per¬ 
formance  of  the  system  can  be  judged  by 
three  criteria:  speed,  compactness,  and 
utility. 

Tradeoffs  and  Performance 

Speed 

Most  people,  when  asked  what  they 
most  want  in  a  computer,  will  say  that 
they  want  more  speed.  In  a  Forth  system, 
people  talk  about  two  measures  of  speed: 
compilation  time,  or  the  time  to  add  defi¬ 
nitions  to  the  system,  and  execution  time, 
or  the  time  to  execute  those  definitions. 
Compilation  time  is  governed  by  factors 
such  as  I/O  speed  and  dictionary  struc¬ 
ture.  Execution  time  is  governed  by  the 
choice  of  address  interpreter  and  the  ratio 
of  assembly  definitions  to  high-level 
definitions.  In  this  article,  I  address  only 
execution  speed. 

Compactness 

One  of  the  greatest  advantages  of  a 


threaded  language  is  its  economy  of  com¬ 
puter  memory.  A  typical  Forth  system  on 
an  8 -bit  computer  is  less  than  16Kb  in 
size  and  includes  an  editor,  assembler, 
interpreter,  compiler,  and  disk  system.  If 
small  size  is  your  goal,  your  system  will 
run  somewhat  slower  than  one  optimized 
for  speed.  Compactness  is  affected  by  the 
ratio  of  assembly  definitions  to  high-level 
definitions.  The  address  interpreter  also 
has  an  impact  on  the  size  of  the  overall 
system. 

Utility 

Unfortunately  not  all  factors  fall 
neatly  into  two  piles,  one  marked  “speed” 
and  the  other  marked  “compactness.” 
Some  factors  influence  the  usability  of 
the  final  system.  For  example,  if  you 
want  to  use  programs  already  written  for 
another  computer  (such  as  an  IBM  PC), 
you  can  tailor  the  architecture  of  the  new 
Forth  system  to  lessen  the  conversion 
effort;  it  may  mean  using  an  indirect 
threaded  interpreter  instead  of  a  direct 
one.  Another  example  is  the  size  of  the 
data  and  return  stacks.  Some  applications 
demand  greater  than  16-bit  addressing, 
which  is  the  traditional  size  of  Forth’s 
stacks.  To  use  a  stack  wider  than  16  bits 
means  the  Forth  system  must  be  larger. 

The  Address  Interpreter 
—  The  Heart  of  Forth 

In  threaded  languages,  programs  are 
represented  by  a  list  of  addresses.  These 
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addresses  refer  in  some  way  to  executable 
machine  code.  Three  methods  of  imple¬ 
menting  threaded  code  languages  are  pop¬ 
ular:  direct,  indirect,  and  token  threaded 
interpreters.  In  this  sense,  interpreter 
means  the  address  interpreter  —  a  short 
(usually  less  than  10  bytes)  machine- 
coded  routine  that  looks  up  the  address 
of  the  next  high-level  instruction  to  be 
executed. 

From  the  language  user’s  standpoint, 
all  three  address  interpreters  may  appear 
the  same.  As  long  as  the  user  disregards 
preconceived  ideas  about  the  physical 
layout  of  his  or  her  programs,  the  pro¬ 
grams  are  transportable  between  systems 
that  use  different  address  interpreters.  In 
a  few  cases,  it  is  impossible  for  the  user  to 
ignore  the  physical  layout  of  the  programs 
(i.e.,  when  writing  a  binary  program 
loader  that  must  relocate  the  programs 
after  loading  them).3  When  possible, 
Forth  programmers  can  enhance  the  por¬ 
tability  of  their  programs  by  using  only 
built-in  words  that  return  key  addresses, 
such  as  LFA,  CFA,  and  PFA  in  a  fig-Forth 
system. 

Direct  Threaded 

The  fastest  of  the  group  is  the  direct- 
threaded  interpreter.4  In  Figure  1  (page 
18),  the  interpreter  is  calling  a  subroutine 
from  a  main  program.  In  Forth,  a  subrou¬ 
tine  is  any  procedure  (or  word)  already 
defined.  The  IP  in  the  figure  is  the  instruc¬ 
tion  pointer,  a  bit  of  Forth  jargon  that 
refers  to  the  pseudo  program  counter  of 
the  threaded  interpreter. 

With  direct-threaded  code,  the  con¬ 
tents  of  IP  point  directly  to  executable 
machine  code.  To  jump  to  the  code,  the 
processor  jumps  indirectly  via  the  IP 
register.  To  process  the  next  instruction, 
the  microprocessor  must  first  increment 
the  IP  register  to  point  to  it.  Some 
micros,  like  the  MC68000,  accomplish 
this  in  one  step  using  an  “indirect  with 
auto-increment”  addressing  mode. 

Listing  One  (page  22)  presents  the 
MC68000  version  of  the  direct-threaded 
address  interpreter.  At  only  two  instruc¬ 
tions,  it  is  a  marvelously  efficient  mecha¬ 
nism  for  implementing  a  Forth  system. 
The  total  time  taken  to  thread  from  one 
routine  to  the  next  is  expressed  as  16 
clock  cycles  in  the  listing.  In  a  typical 
system  with  an  8  MHz  clock,  the  instruc¬ 
tions  take  2  microseconds.  Since  it’s  only 
4  bytes  long,  it  can  be  appended  to  each 
definition  without  greatly  increasing 
memory  requirements.  (The  alternative  is 
to  keep  this  routine  in  one  location  and 
jump  to  it  from  each  definition.) 

Indirect  Threaded 

Next  fastest  in  the  speed  contest 
is  the  indirect -threaded  interpreter.  Since 
it  uses  one  more  level  of  indirection,  it 
requires  another  memory  fetch  to  thread 
from  one  instruction  to  the  next.  This  is 
the  type  of  interpreter  used  by  all  “fig- 


compatible”  versions  of  Forth,  because  it 
is  somewhat  less  machine  dependent  than 
the  direct-threaded  version.5 

As  you  can  see  in  Figure  2  (page  18), 
the  IP  in  this  machine  points  to  a  location 
called  the  code  field  address,  or  CFA, 
of  the  definition  to  be  executed.  The 
contents  of  the  CFA  point  to  executable 
machine  code.  To  thread  from  one  instruc¬ 
tion  to  the  next,  the  microprocessor  uses 
two  indirect  memory  operations  where 
before  it  used  one.  As  before,  the  micro¬ 
processor  automatically  increments  the 
pointers  as  they  are  used. 

Listing  Two  (page  24)  contains  the 
code  for  an  indirect-threaded  address 
interpreter  in  MC68000  assembly  lan¬ 
guage.  Only  one  instruction  is  added  to 
the  direct  version,  at  a  cost  of  2  bytes  and 
1  microsecond. 

Token  Threaded 

Token-threaded  interpreters  add  yet 
another  level  of  indirection  to  the  process. 
I  did  not  implement  one  in  MC68000 
instructions,  but  this  is  accomplished 
with  one  more  indirect  fetch. 

16 -Bit  Addressing 
and  the  MC68000 

Most  Forth  systems  are  defined  with 


16-bit  data  and  address  elements.  An  ad¬ 
dress  space  of  64Kb  is  enough  for  most 
applications,  and  16-bit  addresses  make 
Forth  a  very  compact  language.  Where 
does  the  address  space  begin  and  end? 
At  zero  and  FFFFh? 

Negative  Addresses? 

The  MC68000  processor  allows  you 
to  define  32-  or  16-bit  addresses  for  any 
operation.  You  can  mix  them  at  will  and 
interchange  data  and  address  registers 
with  impunity.  One  reason  this  works  is 
that  address  registers  (AO  .  .  .  A7)  sign 
extend  their  operands  when  they  are 
loaded.  That  means  that  an  address  of 
0100H  (16  bits)  is  sign  extended  to 
00000100H  (32  bits).  Fine.  The  problem 
is  that  addresses  of  8000H  to  FFFFh 
are  treated  as  negative  addresses  and  are 
sign  extended  to  32  bits  by  loading  the 
upper  16  bits  with  FFFFH  (i.e.,  8000h 
is  sign  extended  to  FFFF8000H).  The 
addressing  space  of  the  MC68000  lies 
on  a  “number  circle”  as  shown  in  Figure 
3  (page  19). 

Many  MC68000-based  computers  do 
not  allow  the  programmer  to  use  the 
memory  region  between  FFFF8000h  and 
00000000H.  In  a  CP/M-68K  computer, 
for  example,  the  operating  system  is 


00007FFFH 


00000000 


H 


FFFF8000h 


Full  32-bit  address  range 


Enlargement  of 
1 6-bit  address  range 


Figure  3. 

Address  range  of  MC68000 
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located  either  at  the  top  or  at  the  bottom 
of  memory.6  Obviously  a  16 -bit  version 
of  Forth  can’t  occupy  both  top  and  bot¬ 
tom  within  a  CP/M-68K  system.  Is  there 
any  way  to  circumvent  the  addressing 
problem  and  still  have  a  16 -bit  version 
of  Forth? 

Address  Independent  Forth 

A  solution  exists  for  both  direct-  and 
indirect-threaded  code  interpreters.  The 
solution  is  to  dedicate  one  register  in  the 
MC68000  to  hold  a  base  address,  or  start¬ 
ing  address,  for  the  Forth  system.  All 
memory  references  are  made  relative  to 
the  base  pointer  (or  BP).  The  resulting 
system  can  run  at  any  address  by  simply 
changing  the  value  of  the  BP  register. 

In  Listing  Three  (page  24),  both 
direct-  and  indirect-threaded  interpreters 
are  shown.  In  the  direct -threaded  version, 
the  IP  register  is  loaded  with  the  correct 
32-bit  address  at  boot-up  and  thereafter 
maintains  a  “real”  (32-bit)  instead  of  a 
“logical”  (16-bit  plus  base  pointer)  ad¬ 
dress;  it  doesn’t  need  to  be  combined 
with  the  BP  register.  The  address  of  the 
executable  code  is  combined  with  the  BP 
register  at  a  cost  of  2  bytes  and  0.75  mi¬ 
croseconds  (still  an  8  MHz  clock).  The 
total  time  for  the  direct-threaded  address 
interpreter  is  now  2.75  microseconds. 

The  indirect -threaded  address  inter¬ 
preter  pays  a  heavier  price.  It  uses  the  BP 


register  twice  at  a  cost  of  2  bytes  and 
0.75  microseconds  per  occurrence.  The 
total  time  for  the  indirect-threaded  ad¬ 
dress  interpreter  is  4.5  microseconds. 

Even  though  they  run  somewhat 
slower,  the  address-independent  versions 
of  Forth  have  greater  utility  than  the  ver¬ 
sions  that  directly  address  memory.  For 
instance,  the  address-independent  versions 
allow  use  of  64Kb  of  memory,  regardless 
of  where  the  memory  is  placed  (as  long 
as  it  is  contiguous ).  In  a  large  address 
space,  you  can  even  keep  several  separate 
copies  of  address-independent  Forth, 
each  running  its  own  application. 

Timing  Comparisons 

These  Forth  systems  were  implement¬ 
ed  on  a  Sage  II  computer,  a  MC68000- 
based  machine  with  512Kb  of  R/W  mem¬ 
ory  and  two  320Kb  floppy  disk  drives.  Its 
processor  runs  at  8  MHz  with  no  memory 
wait  states. 

I  chose  benchmark  programs  (List¬ 
ings  Four,  Five,  and  Six,  pages  24-26) 
that  use  memory  access  functions  instead 
of  disk  I/O  functions.  They  are  programs 
that  I  received  from  Laboratory  Micro¬ 
systems,  a  vendor  of  Z80,  IBM,  CP/M-86, 
and  CP/M-68K  Forth  systems.  Jim  Gil¬ 
breath’s  program  (Listing  Four)  allows 
some  comparisons  to  be  made  with  other 
languages.7 


Two  different  Forth  systems  are 
compared  here;  an  indirect-threaded 
code  version  and  a  direct-threaded  code 
version.  Both  versions  use  a  base  pointer 
register  for  memory  accesses.  Thus  these 
versions  of  Forth  are  insensitive  to  their 
position  in  the  address  space  of  the  MC¬ 
68000. 


Results 

Table  1  (page  20)  summarizes  the 
results  of  the  three  benchmark  programs. 
Actually  the  indirect-threaded  interpreter 
didn’t  do  too  badly.  Instead  of  the  40% 
speed  advantage  you  may  have  expected 
from  the  address  interpreter  times,  the 
direct -threaded  code  averaged  only  20% 
or  so  faster.  Why?  Because  the  micro¬ 
processor  spends  only  part  of  its  time 
executing  the  address  interpreter.  Most 
of  the  time  is  spent  executing  code  that 
implements  the  Forth  instructions. 

Compare  the  Sieve  of  Eratosthenes 
times  to  those  published  in  Byte  maga¬ 
zine.8  The  program  of  Listing  Four  was 
run  10  times,  as  were  the  programs  in 
Byte  (Table  2,  page  20).  As  you  can 
see,  the  Forth  systems  run  slower  than 
native  code  compilers  on  this  particular 
benchmark.  In  all  honesty,  Forth  programs 
will  almost  always  run  slower  than  those 
produced  by  a  good  native  code  compiler. 
Although  slower,  the  Forth  system  is 
interactive  (much  like  a  BASIC  interpre¬ 
ter),  which  speeds  program  coding  and 
testing.  The  native  code  compilers  adhere 
to  the  cumbersome  cycle  of  edit,  com¬ 
pile,  assemble,  link,  load,  and  debug  for 
creating  programs. 

In  summary,  Forth  and  the  Motorola 
68000  microprocessor  are  made  for  each 
other.  Used  together,  they  offer  a  fast, 
powerful  programming  environment.  The 
MC68000  processor  allows  the  language 
designer  great  flexibility  in  designing  a 
Forth  system. 


Byte  Interface  Age  Eight  queens 

+ - + - + - + 


Indirect 

19.5 

9.5 

8.5 

Direct 

15.5 

7.5 

7.0 

+ - + - + - + 


Improvement  |  21%  |  21%  |  18% 

+ - + - + - + 

Table  1 . 


68000  8  MHz 

Assembly 

0.49 

Andrew  Wood 

68000  8  MHz 

SMPL  (Ebnek) 

2.6 

Steve  Keller 

68000  8  MHz  (Sun  PM68K) 

ROS 

Pascal  (Telesoft) 

4.28 

Craig  Maudlin 

68000  8  MHz  (Sun  PM68K) 

ROS 

Ada  (Telesoft) 

4.4 

Craig  Maudlin 

68000  Wicat  150WS 

MCS/Unix 

C  (Johnson) 

4.71 

Authors 

68000  8  MHz  (HP-9830) 

ROS 

Ada  (Telesoft) 

5.0 

Craig  Maudlin 

68000  8  MHz  (HP-9830) 

ROS 

Pascal  (Telesoft) 

5.0 

Craig  Maudlin 

68000  8  MHz 

UCSD 

Pascal  (Softech  native) 

5.0 

Softech 

68000  8  MHz 

Pascal  (IMS  Inc.) 

5.8 

Steve  Keller 

68000  8  MHz  (HP-9830) 

Pascal  1.0 

Pascal  (Hewlett-Packard) 

5.9 

Craig  Maudlin 

68000  Charles  River  68 

UNOS 

C 

6  3 

Authors 

68000  Wicat  1 50 

Pascal 

6.5 

Richard  Lane 

68000  (4  MHz) 

Pascal  (Pascal  MT) 

9.00 

BYTE,  Sept.  1981 

68000  8  MHz  Exormacs 

C  (Whitesmiths) 

9.82 

Douglas  K.  Beck 

68000  (4  MHz) 

Pascal  (Telesoft) 

10.2 

BYTE,  Sept.  1981 

68000  8  MHz  Exormacs 

Pascal  (Motorola  1 .2) 

11.2 

Douglas  K.  Beck 

68000  8  MHz 

MSP68000 

FORTH  (Hemenway) 

27 

Walt  Patstone 

Table  2.* 

*From  Eratosthenese  Revisited  by  Jim  Gilbreath  and  Jerry  Gilbreath  appearing  in  the  January,  1983  issue  o/BYTE  magazine.  Copyright  ©  1983  Byte 
Publications,  Inc.  Used  with  the  permission  of  Byte  Publications,  Inc. 
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(Listing  begins  below) 


Glossary  of  Terms 


address  interpreter  The  short  machine  lan¬ 
guage  program  that  actually  threads,  or 
executes,  instructions  in  a  threaded  in¬ 
terpretive  language.  On  most  microproc¬ 
essors,  the  address  interpreter  is  2-30 
bytes  long. 

BP  Base  pointer,  an  address  register  that 
holds  the  32-bit  absolute  starting  address 
of  the  Forth  system.  All  memory  refer¬ 
ences  are  made  relative  to  this  address. 

CFA  Code  field  address,  a  Forth  term  that 
denotes  a  special  location  in  a  Forth 
definition  that  holds  the  address  of  exe¬ 
cutable  machine  code.  Used  in  indirect- 
threaded  code  implementations. 

dictionary  In  a  Forth  system,  the  total 
collection  of  "words"  (functions  and 
procedures)  defined  in  the  system. 

direct -threaded  code  Threaded  code  in 
which  the  addresses  point  directly  to 
executable  machine  code  rather  than 
other  addresses.  (See  indirect-  and  token- 
threaded  code.) 

fig  Forth  Interest  Group,  a  collection  of 
Forth  enthusiasts  responsible  for  popu¬ 
larizing  the  language. They  have  published 
public-domain  versions  of  Forth  for 
most  microprocessors.  Most  Forths  sold 
.  today,  even  those  commercially  available, 
are  derivatives  of  fig's  original  effort. 

indirect-threaded  code  Threaded  code  in 
which  the  addresses  point  to  the  address 
of  executable  code.  Uses  one  additional 
level  of  indirection  when  compared  to 
direct -threaded  code. 

inner  interpreter  (See  address  interpreter.) 


IP  Interpretive  pointer,  the  pseudo  program 
counter  for  a  threaded  interpretive  lan¬ 
guage.  The  IP  always  points  to  the  in¬ 
struction  (represented  by  an  address)  to 
be  executed  next. 

NEXT  The  traditional  Forth  name  for  the 
entry  point  into  the  address  interpreter. 
On  some  machines,  the  address  interpre¬ 
ter  is  held  in  one  place  and  jumped  to  as 
needed.  Others  compile  the  address  inter¬ 
preter  after  each  machine  code  routine. 

sign  extend  When  converting  from  a  smaller 
to  a  larger  word  size,  signed  numbers 
must  be  sign  extended  to  maintain  their 
correct  value.  Represented  in  16  bits, 
the  decimal  number  -100  is  FF9Ch. 
Sign  extended  to  32  bits,  it  becomes 
FFFFFF9Ch-  Without  sign  extension,  it 
would  be  0000FF9Ch,  which  is  65436 
decimal.  The  bits  added  to  the  larger 
word  are  set  to  the  value  of  the  sign  bit 
of  the  original  smaller  word. 

threaded  interpretive  languages  Languages 
like  Forth  where  the  subroutines  that 
comprise  programs  are  represented  by 
their  addresses.  As  a  class,  they  are  fast, 
compact,  and  naturally  interactive. 

token-threaded  code  Threaded  code  in 
which  the  addresses  referenced  by  the  IP 
are  entries  in  a  table  of  "tokens."  The 
table  contains  the  address  of  the  code 
field  (CFA),  which  contains  the  address 
executable  code.  Uses  one  additional 
level  of  indirection  when  compared  to 
indirect -threaded  code  and  two  addi¬ 
tional  levels  compared  to  direct-threaded 
code. 

W  The  "word"  pointer  in  an  indirect- 
threaded  interpreter.  The  IP  points  to  a 
location  that  contains  W.  W,  in  turn, 
points  to  an  address  that  contains 
executable  code. 


Listing  One  (Text  begins  on  page  18) 


Note:  A0  is  the  IP  register,  and  Al  is  used  for  scratch. 


Instruction 

bytes 

clocks 

description 

MOVEA  (A0 ) + , Al 

JMP  (Al) 

2 

2 

00  00 

move  (IP)  ->  scratch 
jump  (scratch) 

Total  bytes,  cycles: 

4 

16 

22 
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Forth  and  the  Motorola  68000  (Listing  continued,  text  begins  on  page  18) 

Listing  Two 


Note:  AO  is  the  IP  register,  A1  is  the  W  register,  and  A2  is  used 
for  scratch. 


Instruction 

bytes 

clocks 

description 

MOVEA  (A0)+,A1 

2 

8 

move  (IP)  ->  Word  reg 

MOVEA  (A1)+,A2 

2 

8 

move  (W)  ->  scratch 

JMP  (A2) 

2 

8 

jump  (scratch) 

Total  bytes,  cycles: 

6 

. 

24 

Listing  Three 

Note:  AO  is  the  IP  register,  A1  is  the  base  pointer  register,  and 
DO  is  used  for  scratch. 


Instruction 

bytes 

clocks 

description 

MOVE . W  (AO ) + , DO 

8 

(IP)  ->  scratch 

JMP  0(A1,D0.L) 

14 

jump  (BP+scratch) 

Total  bytes,  cycles: 

6 

22 

Direct  threaded  interpreter 


Note:  AO  is  the  IP  register,  A1  is  the  base  pointer  register,  DO 
is  the  W  register,  and  Dl  is  used  for  scratch. 


Instruction 

bytes 

clocks 

description 

MOVE . W  (AO ) + , DO 

8 

(IP)  ->  Word  reg 

MOVE . W  0  (A1,D0.W)  ,D1 

14 

(BP+W)  ->  scratch 

JMP  0 ( A1 , Dl . W) 

14 

jump  (BP+scratch) 

Total  bytes,  cycles: 

10 

— 

36 

Indirect  threaded  interpreter 


Listing  Four 

Screen  #  16 

0  (  Eratosthenes  Sieve  Prime  Number  program  in  FORTH  ) 

1  (  by  Jim  Gilbreath,  BYTE  September  1981  page  190  ) 

2  FORTH  DEFINITIONS  DECIMAL 

3  8190  CONSTANT  SIZE  0  VARIABLE  FLAGS  SIZE  ALLOT 

4 

5  :  DO-PRIME  FLAGS  SIZE  1  FILL 

6  0  SIZE  0 
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Forth  and  the  Motorola  68000  (Listing  continued,  text  begins  on  page  18) 


7 

8 
9 

10 

11 

12 

13 

14 

15  ;  S 


DO  FLAGS  I  +  C@ 

IF  I  DUP  +  3  +  DUP  I  + 

BEGIN  DUP  SIZE  < 

WHILE  0  OVER  FLAGS  +  C!  OVER  +  REPEAT 
DROP  DROP  1+ 

THEN 

LOOP 

.  . "  primes  "  ; 


Listing  Five 


Screen  #  17 

0  (  Interface  Age  Benchmark  program  ) 

1  :  BENCH  DUP  2/1+  SWAP  . "  Starting  "  CR 

2  1  DO  DUP  I  1  ROT 

3  2  DO  DROP  DUP  I  /MOD 

4  DUP  0=  IF  DROP  DROP  1  LEAVE 

5  ELSE  1  =  IF  DROP  1 

6  ELSE  DUP  0  >  IF  DROP  1 

7  ELSE  0=  IF  0  LEAVE 

8  END IF 

9  ENDIF 

10  ENDIF 

11  ENDIF 

12  LOOP 

13  IF  4  .R  ELSE  DROP  ENDIF 

14  LOOP  DROP  CR  Finished  "  ; 

15  (  see  FORTH  DIMENSIONS  Vol  II,  No.  4,  page  112  ) 


Listing  Six 

Screen  #  29 

0  (  Eight  Queens  Problem,  by  Jerry  Levan  ) 

1  (  Exercise  in  Recursion  from  ) 

2  (  FORTH  DIMENSIONS  II/l  page  6  ) 

3  :  2*  DUP  +  ;  (  double  a  value  ) 

4  :  MYSELF  (  allow  a  word  to  call  itself  by  recursion  ) 

5  LATEST  PFA  CFA  ,  ;  IMMEDIATE 

6  :  I ARRAY  (  makes  an  array  of  l's,  as  given  by  input  ) 

7  <BUILDS  0  DO  1  ,  LOOP 

8  DOES>  SWAP  2*  +  ;  (  leave  indexed  address  in  array  ) 

9  8  I ARRAY  A  (  these  form  workspace  for  solutions  ) 

10  16  I ARRAY  B  16  IARRAY  C  8  I ARRAY  X 

11  :  SAFE 

12  SWAP  OVER  OVER  OVER  OVER  -  7  +  C  @  >R 

13  +  B  @  >R  DROP  A  @  R>  R>  *  *  ; 

14  — > 

15 
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Screen  #  30 

0  (  Eight  Queens  Problem,  continued  ) 

1  :  MARK 

2  SWAP  OVER  OVER  OVER  OVER  -  7  +  C  0  SWAP  ! 

3  +  B  0  SWAP  !  DROP  A  0  SWAP  !  ; 

4  :  UNMARK 

5  SWAP  OVER  OVER  OVER  OVER  -  7  +  C  1  SWAP  ! 

6  +  B  1  SWAP  !  DROP  A  1  SWAP  !  ; 

7  0  VARIABLE  TRIES 

8  :  PRINTSOL  . "  found  on  try  "  TRIES  @  6  .R  8  0 

9  DO  I  X  @  1+  5  .R  LOOP  CR  ; 

10  :  TRY  8  0  DO  1  TRIES  +!  7TERMINAL  IF  QUIT  THEN  DUP  I 

11  SAFE  IF  DUP  I  MARK  DUP  I  SWAP  X  !  DUP  7  < 

12  IF  DUP  1+  7STACK  MYSELF  ELSE  PRINTSOL  THEN 

13  DUP  I  UNMARK  THEN  LOOP  DROP  ; 

14  :  DO- IT  0  TRIES  !  0  CR  TRY  ; 

15  DO-IT  ; S 

End  Listing 
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A  68000  Forth 
Assembler 


o 

X5-  <y  *>, 
<Vn> 

W 


In  this  article  I  will  describe  the  na¬ 
ture  of  assemblers  in  Forth,  and  the 
use  and  implementation  of  a  fairly 
typical  example:  a  Forth  assembler  for 
the  68000.  I  hope  to  make  clear  the 
power  of  such  assemblers,  some  of  the 
trade-offs  involved,  and  why  this  assem¬ 
bler  was  implemented  the  way  it  was. 
For  clarity  I  will  ignore  implementation 
dependencies:  I  will  occasionally  make 
statements  which  are  true  for  my  sys¬ 
tem,  but  which  may  vary  slightly  on 
other  systems. 

In  brief,  a  Forth  system  is  an  inter¬ 
active  programming  environment  in  which 
routines  (called  words)  are  kept  in  a  data 
structure  called  the  dictionary.  The  pro¬ 
grammer  can  add  new  words  which  can 
be  defined  either  in  terms  of  existing 
words,  or  in  terms  of  machine  code.  An 
assembler  in  a  Forth  environment  is  a 
tool  for  defining  words  using  machine 
code.  It  is  not  intended  for  writing  stand¬ 
alone  applications  in  assembler.  A  Forth 
cross-assembler  is  a  very  similar  tool 
which  produces  code  which  will  run  in  a 
different  environment,  possibly  on  a  dif¬ 
ferent  processor.  This  article  is  concerned 
only  with  ordinary  Forth  assemblers. 
These  assemblers  are  small  because  they 
use  the  existing  Forth  words,  so  the  size 
of  the  assembler  is  only  an  increment 
to  the  size  of  the  system.  For  example, 
this  assembler  requires  about  3  Kbytes, 
added  to  a  12  Kbyte  system.  For  com¬ 
parison,  the  assembler  provided  with 
CP/M-68K  requires  44K  plus  6K  for  a 
symbol  table  file. 

In  writing  applications,  the  assembler 
is  rarely  used  until  the  algorithms  have 
been  tested  and  debugged  in  high  level 
code.  At  the  initial  stages  of  a  design,  the 
programmer’s  time  is  far  more  valuable 
than  the  machine’s.  When  an  application 
is  running,  it  might  prove  to  be  too  slow. 
If  so,  you  now  decide  where  the  most 
time  is  being  spent,  and  rewrite  just  that 
routine  in  code.  Repeat  this  process  until 
the  application  is  fast  enough.  Avoid 
writing  in  code  unless  necessary:  it  limits 
portability.  In  rare  cases,  if  you  have  a 
very  time-critical  application,  you  may 
end  up  with  nearly  everything  in  code. 


by  Michael  A.  Perry 


Michael  A.  Perry,  Even/Odd  Designs, 
Berkeley,  CA  94702. 


Even  then,  writing  the  high  level  code 
first  will  produce  results,  and  the  final 
product,  most  quickly.  Always  be  pre¬ 
pared  to  throw  out  early  designs  and  start 
over.  The  key  to  success  is  iteration:  do  it 
over  until  you  get  it  right.  This  is  why  it 
is  so  important  to  implement  a  simple 
version  of  the  application  first  to  find  out 
if  your  basic  idea  is  workable. 

The  names  of  Forth  words  can  be 
any  string  of  up  to  31  ASCII  characters 
excluding  the  space  character.  Words  in 
the  dictionary  are  organized  into  groups 
called  vocabularies.  The  assembler  is  a 
vocabulary  named  ASSEMBLER.  Most 
words  in  the  assembler  are  named  for  the 
instruction  mnemonics  of  the  host  pro-1 
cessor,  in  this  case  the  68000.  When  such 
a  word  is  executed,  it  appends  an  appro¬ 
priate  sequence  of  bytes  to  the  diction¬ 
ary.  Other  words  in  the  assembler  are 
used  for  addressing  modes,  structured 
conditionals,  macros,  and  possibly  other 
extensions.  Given  a  few  constraints,  it  is 
possible  to  implement  a  very  powerful 
assembler  very  simply. 

The  two  major  constraints  are  on 
syntax  and  forward  reference.  As  is  gen¬ 
erally  true  in  Forth,  forward  reference 
is  not  allowed.  That  is,  you  cannot  use 
anything  until  it  is  defined.  I  believe  this 
is  a  good  thing,  but  this  issue  raises  end¬ 
less  debate  and  I  will  not  try  to  end  it 
here.  It  is  much  simpler  (and  therefore 
faster  in  execution)  to  use  an  operator 
final  syntax.  This  means  that  instructions 
are  written  in  the  form:  source  destina¬ 
tion  operation.  While  unconventional,  this 
format  is  very  flexible  and  simple  to  use. 
An  algebraic  syntax  pre -processor  could 
easily  be  used  if  the  speed  degradation 
could  be  tolerated. 

The  dictionary  grows  towards  high 
memory  as  new  words  are  added.  Most 
data  structures  are  also  allocated  within 
the  dictionary.  The  variable  DP  points  to 
the  next  free  address.  The  word  HERE 
returns  the  value  of  DP.  The  word  , 
(comma)  appends  a  16-bit  value  to  the 
dictionary.  The  word  C,  (c-comma)  ap¬ 
pends  an  8-bit  value  (one  byte).  The  as¬ 
sembler  is  built  on  comma  and  c-comma. 

Error  Control 

When  I  use  an  assembler,  I  expect  it 
to  have  several  important  characteristics. 
The  first  is  correctness:  good  input  must 
result  in  good  output.  The  second  is 
speed:  I  want  the  assembler  to  produce 
its  output  as  rapidly  as  is  possible.  The 
third  is  predictability:  when  I  write  as¬ 


sembly  code,  I  will  do  the  optimizing. 
I  will  not  use  an  optimizing  assembler  - 
I  hate  surpr.ses.  Finai'y  I  prefer  to  avoid 
overlaid  (or  “smart”)  operators  -  that  is, 
operators  which  allow  me  to  be  lazy  by 
deciding  that  this  time  ADD  really  means 
ADDI  or  ADDQ  or  '»'batever.  They  are 
slower  and  less  predictable  than  non- 
overlaid  operators.  Because  Forth  assem¬ 
blers  are  e;  tensible,  any  user  can  add 
smart  operal  ors  on  top  of  the  dumb  ones 
if  he  so  desires. 

Any  amount  of  viror  checking  can 
be  added  to  an  assembler.  Ideally,  an 
assembler  should  only  accept  legal  input. 
It  can  be  expensive,  however,  to  provide 
exhaustive  error  control,  especially  in 
terms  of  speed.  Fortunately,  most  errors 
can  be  caught  simply.  The  cost  of  check¬ 
ing  that  the  s<ack  depth  does  not  change 
during  a  definition  (nothing  extra  is  left 
or  consumed)  and  that  the  structured 
conditionals  are  balanced  is  very  small. 

The  next  level  of  error  detection  is 
to  test  tha1  only  allowed  addressing 
modes  are  used  with  each  instruction. 
For  a  very  orthogonal  architecture,  this 
is  very  easy.  Unfortunately,  the  68000 
does  not  quite  qualify,  despite  advertising 
claims  to  the  contrary.  Even  so,  many 
cases  can  be  easily  checked.  Although  I 
do  not  ordinarily  use  them,  I  have  in¬ 
cluded  some  words  for  checking  that 
instructions  are  given  valid  addressing 
modes.  ??Dn  will  abort  unless  fed  a  data 
register  direct  mode.  ??An  will  abort  un¬ 
less  fed  an  address  register  direct  mode. 
??jmp  will  abort  unless  fed  a  valid  jump 
mode.  Beyond  this  level,  one  is  faced 
with  rapidly  diminishing  returns;  much 
more  effort  gives  only  small  gains. 

Assembler  Usage 

For  a  detailed  and  fairly  accurate 
description  of  the  Motorola  MC68000, 
see  the  manual.2  As  an  example  of  how 
the  assembler  is  used,  take  the  definition 
of  the  word  FILL,  which  fills  an  area  of 
memory  with  a  given  byte.  It  is  used  in 
the  form: 

address  length  byte  FILL 

Notice  that  FILL  takes  three  parameters 
from  the  stack  and  does  not  leave  any. 
The  definition  of  FILL  is  shown  in  Figure 
1  (page  29).  The  word  CODE  is  a  defining 
word.  It  creates  a  header  for  the  new 
word  named  FILL  and  sets  its  code  field 
to  point  to  its  parameter  field,  and  leaves 
the  system  in  execution  state.  The  assem¬ 
bler  does  not  use  the  Forth  compiler,  as 
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is  often  incorrectly  assumed.  The  header 
is  something  like  a  symbol  table  entry. 
The  code  field  of  any  word  points  to  the 
code  to  be  executed  for  that  word.  Ordi¬ 
narily,  all  words  with  the  same  parent 
(defining  word)  share  a  code  segment  in 
the  parent.  Words  defined  by  CODE  con¬ 
sist  of  a  unique  code  segment,  contained 
in  the  body  of  the  word,  which  is  pointed 
to  by  the  code  field  of  the  word.  The  re¬ 
maining  words  in  the  definition  assemble 
a  sequence  of  bytes  into  the  body  of  the 
word. 

Assembler  opcode  mnemonics  such 
as  MOVE  use  the  word  comma  to  append 
numbers  in  line  to  the  parameter  field  of 
the  word  being  defined.  If  the  new  word 
is  to  return  to  Forth  after  executing,  its 
definition  will  end  with  NEXT.  NEXT  is 
a  macro  which  assembles  a  jump  to 
Forth’s  address  interpreter.  Its  definition 
is 

:  NEXT  (NEXT)  #)  JMP  ; 

where  (NEXT)  is  the  address  of  the  inter¬ 
preter,  #)  indicates  the  “absolute  word 
address”  mode,  and  JMP  uses  comma  to 
append  the  proper  opcode  and  address  to 
the  word  being  defined.  END-CODE 
marks  the  end  and  does  some  error  check¬ 
ing  and  housekeeping. 

SP  is  the  name  of  the  Forth  virtual 
machine’s  stack  pointer  register.  The  word 
SP  leaves  a  value  on  the  stack,  represent¬ 
ing  direct-addressing  mode  using  A7  (ad¬ 
dress  register  7).  The  word  A7  has  the 
same  effect;  both  are  just  constants.  The 
word  )+  modifies  the  value  left  by  SP  to 
indicate  the  “indirect  with  auto-incre¬ 
ment”  addressing  mode.  How  this  works 
will  be  covered  later.  The  word  DO  repre¬ 
sents  data  register  0. 

The  word  MOVE  assembles  a  68000 
move  instruction.  MOVE  requires  a  pair 
of  arguments,  each  representing  an  ad¬ 
dressing  mode.  In  this  case,  the  assembled 
code  will  move  16  bits  from  the  address 
pointed  to  by  SP  into  DO,  and  increment 
SP  by  two.  The  size  of  the  operation  is 
determined  by  the  contents  of  the  vari¬ 
able  SIZE,  and  defaults  to  16-bit  at  the 
start  of  each  definition.  SIZE  is  set  by 
BYTE,  WORD,  and  LONG.  Notice  the 
difference  between  WORD  in  the  AS¬ 
SEMBLER  vocabulary  and  WORD  in  the 
FORTH  vocabulary.  In  the  FORTH  vo¬ 
cabulary,  the  word  WORD  accepts  the 
next  token  from  the  text  input  stream. 

The  word  CODE  leaves  the  system  in 
the  ASSEMBLER  vocabulary,  so  the  cor¬ 
rect  WORD  will  be  found.  The  word 
LMOVE  was  added  as  a  special  case  of 
MOVE,  because  of  the  register  shuffle 
mentioned  earlier.  LMOVE  always  as¬ 
sembles  a  LONG  MOVE,  without  chang¬ 
ing  SIZE.  Notice  the  use  of  DO  and  LOOP 
in  the  assembler.  DO  is  passed  a  data 
register  which  will  contain  the  loop  count 
at  execution  time.  DO  passes  HERE  and 
the  register  on  to  LOOP,  which  assembles 


a  DBRA  back  to  the  DO,  using  the  given 
register. 

Implementation 

There  are  many  possible  and  two 
major  approaches  used  in  writing  assem¬ 
blers  in  Forth.  One  method  is  to  use 
many  variables  which  contain  state  infor¬ 
mation,  and  which  are  used  by  the  in¬ 
struction  mnemonic  words  to  control  as¬ 
sembly,  then  cleared  for  use  by  the  next 
instruction  assembling  word.  A  more 
common  and  more  desirable  approach  is 
used  here.  Almost  all  information  is 
passed  on  the  stack,  which  does  not  need 
to  be  initialized. 

There  are  also  two  major  approaches 
to  interpreting  the  addressing  mode  in¬ 
formation  passed  to  an  assembling  word. 
One  is  to  use  something  equivalent  to 
nested  IF  —  ELSE  statements  to  step 
through  a  sequence  of  choices  (condi¬ 
tional  branches)  of  what  to  do.  The  other 
approach,  used  here,  is  to  have  the  ad¬ 
dressing  mode  words  pass  values  which 
can  simply  be  masked  and  merged 
(ANDed  and  ORed)  to  produce  the  re¬ 
quired  machine  code  values.  In  either 
case  the  resulting  numbers  are  then  ap¬ 
pended  to  the  dictionary.  Logic  calcula¬ 
tions  proceed  far  faster  than  decisions  as 
a  rule,  and  so  the  assembler  tends  to  be 
much  faster  when  using  them. 

While  reading  the  following  descrip¬ 
tions,  refer  to  the  source  code  listing 
screens  and  their  shadow  (comment) 
screens  (pages  35-42).  The  key  idea  to 


look  for  here  is  that  a  machine  code  in¬ 
struction  is  viewed  as  a  collection  of  bit 
fields.  These  bit  fields  are  specified  in  the 
manual  for  the  CPU  chip.  Some  are  com¬ 
mon  to  many  instructions,  like  the  source 
and  destination,  mode  and  register  fields. 

As  mentioned  earlier,  instructions 
which  need  to  know  the  size  of  the  data 
to  be  operated  on  generally  use  the  vari¬ 
able  SIZE.  The  position  of  the  bit  fields 
which  control  data  size  moves  around 
more  than  any  other.  Nearly  all  required 
values  are  built  into  the  value  of  SIZE  in 
each  of  the  three  cases:  BYTE,  WORD, 
and  LONG.  Notice  that  at  this  point  in 
the  code  I  switched  to  OCTAL.  The 
68000  instructions  contain  many  3-bit 
fields  and  can  be  neatly  and  most  natu¬ 
rally  represented  as  octal  digits.  1  was 
forced  to  temporarily  forget  my  bias 
towards  hexadecimal.  The  bit  fields  for 
modes  and  registers  are  usually  in  the 
pattern  shown  in  Figure  2  below. 

In  defining  the  words  which  specify 
registers  and  addressing  modes,  I  indulged 
in  a  small  trick.  I  created  a  multi-defining 
word,  REGS,  which  uses  CONSTANT  in 
a  loop  to  CREATE  several  related  con¬ 
stants.  REGS  is  used  only  twice:  once 
for  the  data  registers  and  once  for  the 
address  registers,  which  are  mode  0  and 
mode  1 : 

Mode  0  is  data  register  direct,  so  D5  is 

5005. 

Mode  1  is  address  register  direct,  so  A3 

is  31 13. 


CODE  FILL  (S  adr  len  val  —  ) 

SP  )+  DO  MOVE  (  pop  'val'  into  D0  ) 

SP  )+  D1  MOVE  (  pop  'len'  into  D1  ) 

SP  )  +  D7  MOVE  (  pop  'adr'  into  D7  whose  high  half  is  0  ) 

D7  A0  LMOVE  (  move  all  of  D7  into  A0  ) 

1  D1  SUBQ  (  decrement  D1 :  DBRA  goes  to  -1,  not  to  0  ) 

D1  DO  D0  A0  )+  BYTE  MOVE  LOOP 

(  loop  until  D1  is  -1,  each  time  moving  the  byte  in  D0  to 
the  address  in  A0 ,  and  incrementing  A0  ) 

NEXT  (  compile  a  jump  to  'next'  ) 

END-CODE  (  end  definition  ) 

Figure  1 . 

Definition  of  FILL.  An  example  of  the  Motorola  MC  68000  Assembler. 


op-code  I  dest  reg  I  dest  mode  I  source  mode  I  source  reg  I 
15  12  I  11  9  I  8  6  I  5  3  I  2  0  I 


Figure  2. 

The  usual  pattern  of  bit  fields  for  modes  and  registers. 
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Words  defined  by  MODE  are  used 
after  an  address  register,  and  replace  the 
two  mode  digits  (which  were  1)  with  the 
new  mode  values.  This  is  done  by  ANDing 
off  the  old  values  and  ORing  in  the  new. 
They  are  all  address  register  indirect, 
with  extras. 

Mode  2  is  address  register  indirect,  so 
A6  )  is  6226. 

Mode  3  is  the  same,  with  post -increment, 
so  A7  )+  is  7337. 

Mode  4  is  the  same  with  pre-decrement, 
so  A7  -)  is  7447. 

Mode  5  is  the  same,  plus  displacement,  so 
123  A1  D)  is  1551,  with  the  displace¬ 
ment  value  (123)  remaining  unaf¬ 
fected  under  the  register/mode  value 
on  the  stack. 

Mode  6  is  the  same,  plus  an  index  and  a 
displacement. 

123  D4  A1  DI)  is  123  under  4004 
under  1661. 

The  remaining  possible  mode  value, 
mode  7,  is  used  for  all  remaining  modes, 
which  are  distinguished  by  values  in  the 
register  fields.  These  modes  are  defined 
as  constants.  #)  is  0770,  and  represents 
the  absolute  (16-bit)  addressing  mode. 
The  name  represents  “immediate  indi¬ 
rect”  (think  about  it). 

L#)  is  1771,  and  represents  the  long  ab¬ 
solute  (32-bit)  addressing  mode. 

PCD)  is  2772,  and  represents  the  program 
counter  relative  with  displacement 
mode. 

123  PCD)  is  123  under  2772. 

PCDI)  is  3773,  and  represents  the  pro¬ 
gram  counter  relative  displaced,  in¬ 
dexed  mode. 

123  D4  PCDI)  is  123  under  4004  un¬ 
der  3773. 

#  is  4774,  and  represents  immediate  data, 
16  or  32  bits. 

456  #is  456  under  4774. 

Notice  that,  in  every  case,  from  one 
to  three  items  (16-bit  numbers)  are  left 
on  the  stack  to  represent  an  addressing 
mode.  The  top  item  usually  becomes  part 
of  the  first  16  bits  of  an  instruction,  along 
with  the  op-code.  Extra  items,  if  any,  are 
assembled  following  the  op-code  word. 

Certain  fields  are  selected  (by  mask¬ 
ing  off  the  rest)  more  frequently  than 
others.  The  word  FIELD  creates  words 
which  select  given  fields.  RS  and  RD 
select  the  source  and  destination  register 
fields.  MS  selects  the  source  mode  field. 
The  generic  term  for  a  completely  speci¬ 
fied  addressing  mode  is  an  effective  ad¬ 
dress  (EA).  The  word  EAS  selects  the 
source  effective  address,  which  consists 
of  the  source  mode  and  register  fields. 
LOW  selects  the  low  8  bits.  The  op-code 
word  often  contains  an  EAS  field.  The 
word  SRC  performs  OVER  EAS  OR, 
which  installs  that  field  into  the  op-code 
word.  The  word  DST  installs  the  destina¬ 
tion  register  field. 


The  Forth  virtual  machine  contains 
five  registers.  These  are  assigned  to  par¬ 
ticular  68000  registers.  For  convenience, 
either  the  68000  or  virtual  machine  regis¬ 
ter  names  may  be  used  with  the  assembler. 

Any  mode  with  extra  values  assem¬ 
bled  following  the  op-code  word  is  said 
to  use  extended  addressing.  The  extended 
addressing  modes  are  handled  by  six 
words  and  a  buffer.  DOUBLE?  leaves  a 
flag  which  is  true  if  the  mode  on  top  of 
the  stack  requires  that  32  extra  bits  be 
assembled.  INDEX?  looks  at  a  mode,  and 
modifies  its  extra  items  into  the  proper 
format  if  it  is  an  indexed  mode.  MORE? 
leaves  a  true  flag  if  the  mode  has  extra 
items.  MORE,  appends  any  extra  items 
to  the  dictionary  (following  the  op -code 
word). 

Some  instructions  require  two  modes, 
to  specify  both  source  and  destination  ad¬ 
dresses.  The  source  mode  is  specified  first, 
so  it  is  below  the  destination  mode  on  the 
stack.  Each  mode  consists  of  one  to  three 
values  on  the  stack.  The  source  mode  is 
used  before  the  destination  mode,  so  it  is 
necessary  to  move  the  destination  mode 
values  to  a  buffer  until  needed.  EXTRA? 
saves  any  extra  items  in  a  buffer  named 
EXTRA,  and  leaves  only  the  mode  value. 
EXTRA,  retrieves  such  extra  items  and 
appends  them  to  the  dictionary. 

Most  of  the  rest  of  the  assembler 
consists  of  the  definition  and  use  of 
defining  words  which  create  groups  of 
mnemonics.  A  couple  of  examples  will 
suffice.  If  you  are  not  familiar  with  de¬ 
fining  words  in  Forth,  you  should  be. 
That  is  its  most  powerful  feature. 

The  word  IMM  creates  words  which 
implement  immediate  assembler  instruc¬ 
tions.  I  will  repeat  its  definition  here  and 
go  through  it  in  detail. 

:  IMM 

CONSTANT 

DOES>  @  >R  EXTRA?  EAS  R>  OR 

SZ3  ,  LONG?  ?, , EXTRA  ; 

Usage:  3000  IMM  ADDI 
Assembly:  n  ea  ADDI 

example:  123  A5  )  ADDI 

Each  time  IMM  is  used  to  define  an 
instruction  mnemonic  word,  it  saves  a 
constant  value  in  the  definition  of  that 
word  which  distinguishes  it  from  other 
immediate  words.  That  value  is  the  op¬ 
code  for  the  instruction.  Immediate  in¬ 
structions  contain  the  following  bit  fields: 

I  op -code  I  size  I  mode  I  reg  I 
I  15  8  I  7  6  I  5  3  I  2  01 

These  are  followed  by  16  or  32  bits  of 
data.  When  the  instruction  word  is  exe¬ 
cuted,  it  performs  the  code  following 
DOES>  in  IMM,  with  the  address  of  its 
own  parameter  field  on  the  top  of  the 
stack.  At  that  address  is  the  constant 


(op-code)  built  into  it.  That  value  is 
read  by  the  word  @  and  saved  on  the 
return  stack  by  >R.  ADDI  is  passed  the 
immediate  data  to  use  under  the  mode 
items  for  an  effective  address.  EXTRA? 
saves  any  extra  items,  EAS  selects  the 
mode  and  register  fields  to  use,  then  the 
op-code  is  retrieved  from  the  return 
stack  with  R>  and  combined  with  the 
EAS  by  OR.  SZ3  installs  the  appropriate 
size  bits  from  SIZE,  and  the  word  comma 
appends  the  op -code  word  to  the  dic¬ 
tionary.  This  leaves  only  the  immediate 
data  on  the  stack,  and  LONG?  determines 
whether  ?,  should  append  16  or  32  bits 
to  the  dictionary.  Finally,  the  saved 
extras  (if  any)  are  retrieved  and  ap¬ 
pended  following  the  immediate  data  by 
, EXTRA. 

Numerous  other  defining  words  built 
along  very  similar  lines  are  used  to  define 
most  of  the  remaining  instructions.  Many 
words  are  in  a  class  by  themselves  and  so 
are  defined  by  the  word  colon  (:),  just 
like  macros.  The  conditional  instructions 
are  so  regular  that  I  used  another  trick  de¬ 
fining  word.  SETCLASS  repeatedly  uses 
a  given  defining  word,  each  time  with  a 
different  argument,  to  define  multiple 
words  at  once.  It  is  used  to  define  all  46 
conditional  instructions  by  repeating  each 
of  the  three  defining  words  16  times. 
Two  junk  mnemonics  are  also  created 
which  will  not  be  used.  It  would  be  slight¬ 
ly  better  in  this  case  to  define  all  46 
words  separately,  but  I  wanted  to  show 
what  kinds  of  things  can  be  done. 

Finally  we  come  to  the  structured 
conditionals.  The  following  examples  will 
be  discussed: 

A3  )+  Dl  CMP  0< 

IF  DO  A 7  )  MOVE 

ELSE  A 7  )  DO  MOVE 

THEN 

BEGIN  A3  D2  CMP  0= 

WHILE  A0  )+  DO  MOVE 

REPEAT 

In  the  first  example  the  result  of  a 
comparison  is  to  affect  certain  flags  in  the 
status  register.  IF  assembles  a  conditional 
branch  instruction  whose  op -code  (and 
condition)  is  specified  by  0<,  which 
leaves  the  value  for  a  jump  if  greater  or 
equal  to  zero.  ELSE  resolves  the  branch 
address  for  the  IF  and  assembles  an  un¬ 
conditional  branch  whose  address  is  re¬ 
solved  by  THEN.  WHILE  assembles  a 
conditional  branch  to  the  address  follow¬ 
ing  the  REPEAT,  which  assembled  an  un¬ 
conditional  branch  back  to  the  BEGIN. 

Notice  that  there  is  no  need  for  any 
labels.  A  primary  source  of  clutter  in 
ordinary  assembler  code  is  the  large  num¬ 
ber  of  labels  with  meaningless  names  used 
for  branch  destinations.  Also  note  that 
the  structured  conditionals  defined  here 
use  only  one-byte  offsets.  Because  the  as¬ 
sembler  is  one  pass,  it  is  necessary  to  re¬ 
serve  the  space  for  the  offset  before  its 
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size  is  known.  Since  CODE  routines  in 
Forth  are  always  rather  short,  one  byte 
is  enough.  If  it  is  not,  I  simply  replace 
these  definitions  with  nearly  identical 
definitions  which  use  only  16-bit  offsets. 

Finally,  it  should  be  noted  that  there 
is  no  need  for  words  to  create  data  struc¬ 
tures  for  use  with  the  assembler.  A  Forth 
assembler  is  part  of  a  Forth  environment, 
and  any  data  structure  created  by  ordi¬ 
nary  Forth  defining  words  can  be  referred 
to  by  assembler  routines.  For  example: 

VARIABLE  FOO 

CODE  BAR  FOO  #)  NEG  NEXT 

END-CODE 

BAR  will  negate  the  contents  of  the 
variable  FOO. 
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( Listing  begins  below) 


A  68000  Forth  Assembler 


(Text  begins  on  page  28) 


0  \  68000  Assembler 

1  VOCABULARY  ASSEMBLER  I  MEDIATE 

2  (  ’  ASSEMBLER  CFA  ’  ;CCDE  10  + 


06Jun83map  Assembler 


ASSEMBLER  DEFINITIONS 


END-CODE  (S  -  ) 
ISNAP  SNAP  ; 

?,  (S  En23  n!  1 


CURRENT  8  CONTEXT 


8  1  14  +THRU 

9  FORTH  DEFINITIONS 

10  :  LABEL  tS  -  ) 

11  CREATE  [COMPILE]  ASSEMBLER 

12  :  CODE  (S  --  1 

13  LABEL  HERE  DUP  2-  !  ; 

56 

0  \  Sires 
1  OCTAL 

O 

i. 

3  VARIABLE  SIZE 


ASSEMBLER  NORD 


This  code  is  For  syste»s  compatible  Mith  Starting  Forth, 
which  is  very  nearly  79-Standard. 

This  is  a  structured  macro  assembler  which  uses  Motorola 
mnemonics  i  with  few  exceptions)  and  the  following  syntax: 
source  destination  operation.  For  example, 

DO  D2  MOVE  means  copy  the  contents  of  DO  into  D2, 

1  #  SP  -)  MOVE  means  push  a  1  onto  the  parameter  stack. 

(S  means  ’stack  comment’  and  is  equivalent  to  ( 

\  means  ’comment  to  end  of  line’ 

LABEL  is  used  to  name  the  entry  point  to  a  subroutine. 

CODE  creates  a  Forth  word  which  will  be  defined  in  assembler. 


31May83map  Assembler 

Many  instructions  in  the  68000  can  operate  on  8,  16,  or  32  bit 
data.  Rather  than  specify  the  size  individually  for  each 
instruction,  the  variable  SIZE  contains  the  size  information 


4 

:  BYTE 

(S  --  ) 

10000  SIZE  !  ; 

for  any  instruction  which  needs  it.  SIZE  is  set  by  BYTE,  NORD, 

5 

:  NORD 

!S  --  1 

30100  SIZE  !  ;  NORD 

and  LONG. 

6 

:  LONG 

(S  --  ) 

24600  SIZE  !  ; 

7 

:  SZ 

(S  n  - 

CONSTANT  DOES)  i  SIZE  8  AND  OR  ; 

SZ  defines  words  which  select  certain  bits  from  SIZE  and  install 

8 

00300  SZ 

SZ3 

00400  SZ  SZ4 

them  into  the  instruction  being  assembled.  The  size  field  moves 

9  04000  SZ 

SZ40 

30000  SZ  SZ300 

around  considerably,  and  is  even  inverted  in  some  cases. 

10 

:  L0N6? 

(S  --  f 

)  SIZE  8  24600  =  ; 

7L0N6  returns  a  true  flag  if  SIZE  is  LONG. 

11 

12 

:  -SZ1 

(S  op  — 

op’  )  LONG?  IF  100  OR  THEN  j 

-SZ1  is  used  in  a  special  case  where  the  size  flag  has  the 
opposite  sense  of  all  other  size  flags.  Sood  job,  Motorola1 

0  \  addressing  modes 
1  :  REGS  (S  n  -  ) 


(  register  direct  ) 


10  0  DO  DUP  1001  I  X  OR  CONSTANT  LOOP  DROP  ; 


3  :  MODE 


CONSTANT  DOES)  8  SNAP  7007  AND  OR  j 


06Jun83map  Assembler 

This  screen  defines  the  16  data  and  address  registers,  and 
the  various  addressing  modes. 

!R  ;  Notice  that  REGS  defines  several  words  each  time  it  is  used; 


(Continued  on  page  36 ) 
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A  68000  Forth  Assembler  (Listing  continued,  text  begins  on  page  28) 


4  0000  REGS  DO  D1  D2  D3  D4  D5  D6  D7 

5  0110  REGS  AO  A1  A2  A3  A4  A5  A6  A7 

6  0220  NODE  )  (  address  register  indirect  ) 

7  0330  NODE  )  +  (  adr  reg  ind  post-increeent  ) 

8  0440  NODE  -)  (  adr  reg  ind  pre-decre»ent  ) 

9  0550  NODE  D)  (  adr  reg  ind  displaced  ) 

10  0660  NODE  DI)  (  adr  reg  ind  displaced  indexed  ) 

11  0770  CONSTANT  I)  (  mediate  address  ) 

12  1771  CONSTANT  Li)  I  mediate  long  address  ) 

13  2772  CONSTANT  PCD)  (  PC  displaced  ) 

14  3773  CONSTANT  PCDI)  (  PC  displaced  indexed  ) 

15  4774  CONSTANT  «  (  mediate  data  ) 


58 

0  \  fields  and  register  assignaents  06Jun83aap 

1  :  FIELD  (S  n  -  )  CONSTANT  DOES)  i  AND  j 

2  7000  FIELD  RD  0007  FIELD  RS 

3  0070  FIELD  NS  0077  FIELD  EAS 

4  0377  FIELD  LON 


5  i 

:  DN? 

!S  ea  —  ea  flag  ) 

DUP  NS  0=  ; 

6  : 

SRC 

IS  ea  n  —  ea  n’  ) 

OVER  EAS  OR 

7  : 

:  DST 

IS  dn  n  --  n’  ) 

SNAP  RD  OR 

8  A7  CONSTANT  SP  A6  CONSTANT  RP 

9  A5  CONSTANT  IP  A4  CONSTANT  N 

10  A3  CONSTANT  UP 

11  :  ?NQDE  (S  f  --  )  0=  ABORT"  Bad  Node"  ; 

12  :  ??Dn  (S  node  --  »ode  )  DN?  ?HDDE  ; 

13  :  ??An  (S  »cde  --  node  )  DUP  NS  1  =  ?HODE  ; 

14  :  ??JHP  (S  sode  -  node  )  DUP  NS  DUP  2  =  SNAP  4  >  OR 

15  OVER  74  =  NOT  AND  7N0DE  ; 

59 

0  \  extended  addressing  31Nay83aap 

1  :  DOUBLE?  (S  node  —  flag  ) 

2  DUP  Li)  =  SNAP  i  =  LONG?  AND  OR  ; 

3  ;  INDEX?  !S  fn)  Bode  —  (a)  aode  ) 

4  DUP  >R  DUP  0770  AND  AO  DI)  =  SNAP  PCDI)  =  OR 

5  IF  DUP  RD  10  t  SNAP  NS  IF  100000  OR  THEN 

6  S240  SNAP  LON  OR 

7  THEN  R>  j 
3 

9  :  NORE?  (S  ea  --  ea  flag  )  DUP  NS  0040  >  ; 

10  :  .NORE  (S  ea  --  )  NORE? 

11  IF  INDEX?  DOUBLE?  ?,  ELSE  DROP  THEN  ; 

I  T 
i  L 


60 

0  \  extended  addressing  extras  31HayS3*ap 

1  CREATE  EXTRA  HERE  5  ALLOT  5  ERASE  \  teaporary  storage  area 

0 

4. 

3  :  EXTRA?  (S  (nJ  aode  -  aode  )  NORE? 

4  IF  >R  Ri  INDEX?  DOUBLE?  EXTRA  1+  SNAP 

5  IF  2!  2  ELSE  !  1  THEN  EXTRA  C!  R> 

6  ELSE  0  EXTRA  ! 


it  is  a  DO  CONSTANT  LOOP. 

Nords  defined  by  NODE  are  aodifiers,  they  follow  an  address 
register  naie.  For  exaspie,  A5  )  Beans  address  register  5 
indirect.  Exaaples  of  usage  folio*: 

A5  )♦  AS  -)  A5  indirect,  post-increaent  and  pre-decresent. 

3  A5  D)  A5  indirect  with  displaceaent  of  3. 

3  D2  A5  DI)  A5  indirect  indexed  by  D2  with  displaceaent  of  3. 
1234  i)  absolute  address  00001234  (  mediate  indirect  ) 
1234.5678  Li!  absolute  address  12345678  (  long  i*a.  indirect  ). 
3  PCD)  prograa  counter  offset  by  3. 

3  D2  PCDI)  prograa  counter  indexed  by  D2,  offset  by  3. 

1234  i  mediate  data  1234.  (  size  deterained  by  SIZE  ). 


FIELD  creates  itords  which  aask  off  various  bit  fields. 

RS  and  RD  select  the  source  or  destination  register  fields. 

NS  selects  the  source  aode  field.  EAS  selects  the  source 
effective  address  field.  LON  selects  the  low  byte. 

DN?  tests  for  data  register  direct  aode. 

SRC  and  DST  contain  phrases  which  occur  frequently  in  source 
or  destination  aode  calculations. 

These  are  the  virtual  aachine  register  assignaents.  The  Forth 
virtual  aachine  has  five  registers.  Each  of  these  is  assigned 
to  a  68000  address  register.  These  definitions  alio*  your  code 
to  reference  the  virtual  aachine  registers  syabollically.  For 
exaaple,  RP  )+  SP  -)  NOVE  pops  the  top  itea  off  the  return 
stack  and  pushes  it  onto  the  data  stack. 

?NQDE  aborts  if  passed  a  false  flag.  ??Dn  requires  the  data 
register  direct  aode.  ??An  requires  address  register  direct. 
??JNP  requires  any  aode  legal  for  the  JNP  instruction. 

Asseabler 

Nany  of  the  68000’s  addressing  aodes  require  additional 
bytes  following  the  opcode. 

DOUBLE?  leaves  true  if  the  given  aode  requires  32  bits  of 
additional  addressing  inforaation. 

INDEX?  does  nothing  unless  the  given  aode  is  an  indexed  aode, 
in  which  case  it  takes  the  data  under  the  aode  and  packs  it  into 
the  appropriate  foraat. 

NORE?  returns  a  true  flag  if  the  aode  has  extended  addressing. 

, MORE  will  append  the  extended  addressing  bytes  to  the 
dictionary. 


Asseabler 

This  is  a  holding  area  for  destination  extensions. 

EXTRA?  tests  the  aode  for  extensions,  and  if  present  stores 
thea  at  EXTRA. 

, EXTRA  reaoves  the  extras  (  if  any  )  froa  EXTRA  and  adds 
thea  to  the  dictionary. 

(Continued  on  page  38) 
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7  THEN  ; 

8  :  .EXTRA  (S  -  )  EXTRA  C3  ?DUP 

9  IF  EXTRA  1+  SNAP  1  = 

10  IF  3  ,  ELSE  28  2,  THEN  EXTRA  5  ERASE 

11  THEN  ; 

12 
13 

61 


0  \  isaediates  l  address  register  specific  31Hay83*ap 

1  :  IHH  (S  n  ea  --  )  CONSTANT 

2  DOES)  3  >R  EXTRA?  EAS  R>  OR  SZ3  ,  IONS?  ?,  .EXTRA  ; 

3  0000  INN  OR!  1000  IHH  AND I 

4  2000  IHH  SUB I  3000  IHH  ADD  I 

5  5000  IHH  EORI  6000  IHH  CHPI 

6  :  IHHSR  (S  n  ea  -  )  CONSTANT  DOES)  3  S23  2,  ; 

7  001074  IHHSR  ANDDSR  005074  IHHSR  EORDSR 

8  000074  IHHSR  ORDER 

9  :  IB  (S  n  ea  -  )  CONSTANT 

10  DOES)  3  )R  EXTRA?  EAS  SNAP  RS  1000  »  OR  R)  OR  SZ3  ,  .EXTRA  j 

1 1  050000  IQ  ADDA  050400  IB  SUBQ 

12  :  IEAA  (S  ea  An  -  )  CONSTANT  DOES)  3  DST  SRC  SZ4  ,  , HORE  ; 

13  150300  IEAA  ADDA  130300  IEAA  CHPA 

14  040700  IEAA  LEA  110300  IEAA  SUBA 

15 

62 

0  \  shifts,  rotates,  and  bit  aanipuiaticn  06Jun83aap 

1  :  ISR  !S  Da  Dn  !  a  t  Dn  !  ea  --  )  CONSTANT  DOES)  3  >R  DN? 

2  IF  SWAP  DN?  IF  R>  40  OR  >R  ELSE  DROP  SNAP  1000  »  THEN 

3  RD  SNAP  RS  OR  R)  OR  160000  OR  SZ3  , 

4  ELSE  DUP  EAS  300  OR  R3  400  AND  OR  R)  70  AND  100  »  OR 

5  160000  OR  ,  , HORE 

6  THEN  ; 

7  400  ISR  ASL  000  ISR  ASR 

8  410  ISR  LSL  010  ISR  LSR 

9  420  ISR  ROXL  020  ISR  ROXR 

10  430  ISR  ROL  030  ISR  ROR 

11  :  IBIT  (S  ea  Dn  !  ea  n  I  )  CONSTANT  DOES)  3  >R  EXTRA?  DN? 

12  IF  RD  SRC  400  ELSE  DROP  DUP  EAS  4000  THEN 

13  OR  R)  OR  ,  .EXTRA  , HORE  ; 

14  000  IBIT  BTST  100  IBIT  BCHG 

15  200  IBIT  BCLR  300  IBIT  BSET 

63 

0  \  branch,  loop,  and  set  conditionals  31Hay83aap 

1  :  SETCLASS  1  SNAP  0  DO  I  OVER  EXECUTE  LOOP  DROP  ; 

2  :  I  BRA  (S  adr  -  )  400  J  060000  OR  CONSTANT 

3  DOES)  3  SNAP  HERE  2+  -  DUP  ABS  200  < 

4  IF  LON  OR  ,  ELSE  SNAP  2,  THEN  ; 

5  :  IDBR  !S  adr  Dn  -  )  400  >  050310  OR  CONSTANT 

6  DOES)  3  SNAP  RS  OR  ,  HERE  -  ,  ; 


Asseibler 

This  screen  sets  the  pattern  for  the  rest  of  the  asseibler. 
Defining  words  are  created,  then  used  to  define  a  group  of 
siailar  instructions.  The  stack  coaaent  (S  n  ea  i 
indicates  the  allowed  addressing  aodes.  In  this  case,  for 
iaaediate  instructions,  a  nuaber  followed  by  any  effective 
addressing  aode  is  required  before  the  instruction.  For 
exasple  123  A5  !  ORI  aeans  to  perfora  a  logical  OR  of  the 
iaaediate  data  123  with  the  contents  of  the  address  pointed 
to  by  address  register  5,  with  the  result  going  to  that  address 


Asseabler 

ISR  creates  instructions  which  shift  or  rotate. 


IBIT  creates  instructions  which  aampulate  bits. 


Conditionals 

There  are  three  classes  of  conditional  instructions: 
branch,  decreaent  and  branch,  and  set.  In  each  case  there 
is  a  four  bit  field  which  contains  the  condition  code;  this 
field  is  the  only  difference  between  aeabers  of  a  class. 

Rather  than  explicitly  define  sixteen  separate  words  for  each 
class,  the  word  SETCLASS  is  used  to  define  all  sixteen  at  once 

(Continued  on  page  40) 
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A  68000  Forth  Assembler  (Listing  continued,  text  begins  on  page  28) 


7  :  ISET  (S  ea  - 

8  DOES)  S  SRC  , 

9  20  SETCLftSS  IBRA 
10 

11  20  SETCLftSS  IDBR 

12 

13  20  SETCLftSS  ISET 

14 


400  t  050300  OR  CONSTANT 
, MORE  ; 

BRA  BSR  BHI  BLS  BCC  BCS  BNE  BEfi 

BVC  BVS  BPL  BN  I  B6E  BLT  B6T  BLE 

DXIT  DBRfl  DBHI  DELS  DBCC  DECS  DBNE  DBEfi 
DBVC  DBVS  BBPL  DBNI  DBBE  DBLT  DB6T  DBLE 
SET  SNO  SHI  SLS  SCC  SCS  SNE  SES 

SVC  SVS  SPL  SHI  S6E  SLT  SGT  SLE 


by  re-executing  the  ease  defining  word  Kith  a  different  value 
for  the  condition  code  field  each  tise.  Of  the  48  words  so 
defined,  only  DXIT  and  SNO  are  not  actually  useful. 


64 

0  \  soves 


31Hay83aap  Asseabler 


1  i  MOVE  IS  ea  ea  -  ) 

2  EXTRA?  7700  AND  SRC  SI300  ,  , MORE  .EXTRA  ; 

3  :  NOVEQ  IS  a  Dn  -  )  RD  SNAP  LON  OP  070000  OR  ,  ; 

4  :  HOVE >USP  IS  An  -  )  RS  047140  OR  ,  ; 

5  :  HOVEXUSP  IS  An  --  )  RS  047150  OR  ,  ; 

6  ;  HOVER)  IS  n  ea  --  ) 

7  EXTRA?  EAS  044200  OR  -521  ,  ,  .EXTRA  ; 

8  ;  HCVEH<  IS  n  ea  -  ) 

9  EXTRA?  EAS  046200  OR  -SI1  ,  ,  .EXTRA  j 

10  :  NQVEP  IS  Da  d  An  I  d  An  Da  -  ) 

11  DN?  IF  RD  SNAP  RS  OR  410  OR 

12  ELSE  RS  ROT  RD  DR  610  OR 


13 

THEN  -SZ1  2,  ; 

14 

:  LHOVE 

7700  AND  SNAP  EAS  OR  20000  OR  ,  ; 

15 

1  long  reg  eove  ) 

65 

0 

\  odds 

and  ends  31Hay83aap 

1 

:  CHPH 

IS  An8+  Aai+  -  )  RD  SNAP  RS  OR  130410  OR  SZ3  ,  j 

7 

4. 

:  EXG 

IS  Rn  Ra  —  ) 

3 

DN? 

IF  SNAP  DN?  IF  140500  ELSE  140610  THEN  )R 

4 

ELSE  SNAP  DN?  IF  140610  ELSE  140510  THEN  )R  SNAP 

5 

THEN  RS  DST  R)  OR  ,  ; 

6 

EXT 

IS  Dn  --  )  RS  044200  OR  -SZ1  ,  j 

7 

/ 

SNAP 

IS  Dn  -  )  RS  044100  Oft  ,  ; 

8 

STOP 

IS  n  --  )  47162  2,  ; 

9 

TRAP 

IS  n  --  )  17  AND  47100  OR  ,  | 

10 

LINK 

IS  n  An  -  )  RS  047120  OR  2,  ; 

11 

UNLK 

IS  An  -  )  RS  047130  OR  ,  j 

To  keep  the  assembler  siaple,  soae  coaproaise  was  aade  here 
on  coapatability  Kith  Hotorola’s  aneaonics.  The  instruction 
naaes  explicitly  indicate  the  direction  of  data  flow  in  several 
instructions.  For  exaaple, 

HEX  FFFF  SP  -)  HOVER)  will  save  all  registers  on  the  stack. 

I  pronounced  HOVEH-DUT  ) 

LHOVE  is  a  convenience  to  coapensate  for  the  painful  and 
unnecessary  sign  extension  of  address  registers.  It  asseables 
a  long  wove  without  affecting  SIZE.  It  is  used  priaarily  for 
aoving  an  entire  data  register  whose  high  half  is  zero  into 
an  address  register.  This  shuffle  is  neccessary  when  loading 
a  16  bit  address  into  an  address  .register. 


odds  and  ends 

CRPH 

EX6 


EXT 

SNAP 

STOP 

TRAP 

LINK 

UNLK 


06JunS3aap  arithaetic  and  logic 


66 

0  \  arithaetic  and  logic 

1  :  EOR  IS  Dn  ea  --  )  EXTRA?  EAS  DST  SZ3  130400  OR  ,  .EXTRA  ; 

2  ;  IDD  IS  Dn  Da  I  AnS-  AaJ -  )  CONSTANT 

3  DOES)  i  DST  OVER  RS  DR  JSNAP  NS  IF  10  OR  THEN  ,  ; 

4  140400  IDD  ABCD  100400  IDD  SBCD 

5  150400  IDD  ADDX  110400  IDD  SUBX 

6  :  IDEA  IS  ea  Dn  I  Dn  ea  -  )  CONSTANT  DOES)  »  )R  DN? 

7  IF  RD  SRC  R>  OR  SZ3  ,  , HORE 

8  ELSE  EXTRA?  EAS  DST  400  OR  R)  OR  SZ3  ,  .EXTRA  THEN  ; 

9  150000  IDEA  ADD  110000  IDEA  SUB 

10  140000  IDEA  AND  100000  IDEA  OR 


EOR  is  a  special  case. 

IDD  instructions  which  take  either  a  pair  of  data  registers, 
or  a  pair  of  address  registers  used  in  post-increnen t  *ode. 


IDEA  instructions  which  take  an  EA  and  a  data  register,  in 
either  order. 
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11  :  IEAD  (S  ea  Dn  -  )  CONSTANT  DOES)  9  DST  SRC  ,  , MORE  j 

12  040600  IEAD  CHK 

13  100300  IEAD  DIVU  100700  IEAD  DIVS 

14  140300  IEAD  HULU  140700  IEAD  HULS 

15  :  CNF  (S  ea  Dn  -  )  130000  DST  SRC  S23  ,  , MORE  ; 

67 

0  \  arithaetic  and  control  31NayS3aap 

1  :  IEA  (S  ea  --  )  CONSTANT  DOES)  3  SRC  ,  , MORE  ; 

2  047200  IEA  JSR  047300  IEA  JHP 

3  042300  IEA  HOVE)CCR 

4  040300  IEA  MOVE<SR  043300  IEA  MOVE)SR 

5  044000  IEA  NBCD  044100  IEA  PEA 

6  045300  IEA  TAS 

7  :  IEAS  (S  ea  -  )  CONSTANT  DOES)  9  SRC  SZ3  ,  , MORE  ; 

8  041000  IEAS  CLR  043000  IEAS  NOT 

9  042000  IEAS  NE6  040000  IEAS  NEBX 

10  045000  IEAS  TST 

11  :  ICON  (S  --  )  CONSTANT  DOES)  9  ,  ; 

12  47160  ICON  RESET  47161  ICON  NOP 

13  47163  ICON  RTE  47165  ICON  RTS 

14  47166  ICON  TRAPV  47167  ICON  RTR 

15 

68 

0  \  structured  conditionals  ♦/-  256  bytes  01Sep82aap 

1  :  THEN  HERE  OVER  2+  -  ISNAP  1+  C!  ;  :  ENDIF  THEN  ; 

2  :  IF  ,  HERE  2-  ;  HEX 

3  :  ELSE  6000  IF  ISNAP  THEN  ; 

4  :  BEGIN  HERE  ; 

5  :  UNTIL  ,  HERE  -  HERE  1-  C!  j 

6  :  A6AIN  6000  UNTIL  ; 

7  :  NHILE  IF  ; 

8  :  REPEAT  ISNAP  AGAIN  THEN  ; 

9  :  DO  HERE  ISNAP  ; 

10  :  LOOP  DBRA  j 

11  6600  CONSTANT  0=  6700  CONSTANT  0<> 

12  6A00  CONSTANT  0<  6B00  CONSTANT  0>= 

13  6C00  CONSTANT  <  6D00  CONSTANT  >= 

14  6E00  CONSTANT  <=  6F00  CONSTANT  > 

15  DECIMAL 

186 

0  I 

1 

O 
L 

3 

4 

5 

6 

7 

8 

9 

10 
11 
12 


IEAD  instructions  which  take  any  EA  for  the  source,  and  a  data 
register  for  the  destination. 


CMP  another  special  case. 

arithaetic  and  control 

IEA  instructions  which  take  only  an  effective  address. 


IEAS  instructions  which  take  only  an  effective  address 
and  use  SIZE. 


ICON  instructions  which  asseable  a  constant  value. 


Asseabler 

The  usual  coapleaent  of  Forth  conditionals  is  provided, 
including  DO  LOOP.  The  last  is  unusual  in  asseablers.  No 
error  checking  is  provided  for  aisaatched  conditionals  as 
it  is  desirable  when  writing  code  to  be  able  to  easily  bend 
the  rules  of  strictly  structured  code.  Keep  your  code  routines 
saall!  It  will  not  only  aake  your  code  aore  coaprehensible, 
but  also  aake  it  less  error  prone. 

Note  that  any  DBcc  can  replace  LOOP. 


mtittititittittttttttittitittt 

Michael  A.  Perry 
[  1446  Stannage  Avenue 

Berkeley,  California 
94702 

ttimmttittitttttiiiittittttt 


End  Listing 
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Nondeterministic  Control 
Words  in  Forth 
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Programmers  usually  write  programs  with  the  expectation 
that  output  will  depend  only  on  input  and  on  the  se¬ 
quence  of  program  statements,  so  it  might  seem  surprising 
at  first  that  making  the  program  counter  a  random  number 
generator  could  have  other  than  disastrous  consequences.  But, 
in  fact,  the  technique  is  both  interesting  and  useful. 

Of  course,  to  ensure  some  discipline  in  the  system,  we’ll 
let  the  program  counter  be  a  random  number  generator  only  at 
certain  strategic  parts  of  the  program.  The  implementation  of 
a  coin-tossing  controller  is  called,  appropriately,  a  nondeter¬ 
ministic  control  structure.  This  article  will  explore  the  imple¬ 
mentation  and  use  of  nondeterministic  control  structures  in 
Forth.  This  work  is  motivated  largely  by  Henderson’s  discussion 
of  the  use  and  implementation  of  nondeterministic  control  in 
a  variant  of  LISP.1 

The  main  reason  for  introducing  new  data  or  control 
structures  into  a  language  is  to  increase  the  expressiveness  of 
the  language:  Some  algorithms  are  more  naturally  programmed 
using  one  control  structure  than  they  are  using  others.  A  good 
example  of  this  is  the  use  of  recursion,  in  place  of  iteration, 
where  the  problem  to  be  solved  lends  itself  to  progressive  de¬ 
composition  into  similar  but  simpler  problems.  Factors  such  as 
efficiency  and  the  availability  of  temporary  storage  may  influ¬ 
ence  the  ultimate  choice  of  a  programming  technique,  but  the 
expressive  power  of  recursive  control  structures  lies  in  making 
the  solution  itself  simple  and  natural. 

Just  as  recursive  control  is  most  naturally  used  in  the 
solutions  of  a  particular  class  of  problems,  nondeterministic 
control  leads  to  simple  and  natural  solutions  in  another  class 
of  problems,  those  that  employ  backtracking.  As  will  be 
demonstrated,  nondeterministic  control  words  in  Forth  can  be 
used  to  implicitly  encode  the  backtracking  process.  The  result 
is  a  substantial  gain  in  the  ease  of  implementation  of  back¬ 
tracking  algorithms. 

The  nondeterministic  control  structures  described  here 
also  are  useful  for  programming  probabilistic  algorithms.2  A 
probabilistic  algorithm  uses  random  numbers  to  determine 
branchings  in  an  otherwise  deterministic  program  and  may  not 
necessarily  require  backtracking. 

Rabin’s  systematic  study  of  probabilistic  algorithms 
showed  that  in  certain  cases  the  use  of  the  nondeterministic 
approach  could  dramatically  speed  up  computation.3  For 
example,  the  problem  of  determining  whether  a  natural  num¬ 
ber  N  is  prime  becomes  impractical  to  solve  by  conventional 
deterministic  methods  when  N  gets  large  (N*  1060).  Rabin’s 
probabilistic  algorithm  recognized  2400  -  59  3  as  prime  in  a  few 
minutes  of  CPU  time  on  a  medium-sized  computer. 

Probabilistic  and  Backtracking  Algorithms 

The  idea  behind  our  nondeterministic  control  structures  is 
simply  to  toss  a  coin  at  the  chosen  control  point  to  determine 
which  of  the  next  two  Forth  words  is  executed.  The  control 


word  can  be  viewed  as  a  branch  point  in  the  program;  the  coin 
toss  determines  which  branch  the  program  executes. 

The  probabilistic  Forth  control  word  ONEOF  has  the  fol¬ 
lowing  syntax : 

ONEOF  WORD1  WORD2 

When  ONEOF  is  executed,  either  WORD1  or  WORD2  is 
executed  next,  the  choice  being  made  randomly.  After  exe¬ 
cution  of  the  chosen  word,  control  passes  to  the  word  fol¬ 
lowing  WORD2.  ONEOF  is  defined  in  screen  33  in  Listing  One 
(page  52). 

As  an  example  of  the  use  of  ONEOF,  consider  the  follow¬ 
ing  Forth  construct  designed  to  take  an  integer  N  on  the  stack 
and  to  return  an  arbitrary  integer  between  0  and  N: 

:  RANDOMN  DUP  IF  1-  ONEOF  MYSELF  1+  THEN  ; 

MYSELF  is  the  recursive  control  word  used  by  LeVan.4  Execu¬ 
tion  of  RANDOMN  terminates  if  N  is  zero.  Otherwise,  by  a 
toss  of  the  coin,  either  N  is  returned  as  the  choice  or  RAN¬ 
DOMN  is  called  recursively  with  N-l  on  the  stack.  You  might 
compare  RANDOMN  with  CHOOSE,  the  coin  tosser  used  in 
the  definition  of  ONEOF. 

The  advantage  of  nondeterministic  control  in  this  imple¬ 
mentation  of  a  random  number  generator  lies  in  the  ability  to 
think  in  terms  of  an  arbitrary  (random)  choice  without  having 
to  worry  about  the  details.  This  is  the  increase  in  expressive¬ 
ness  we’re  looking  for  in  a  new  control  structure.  For  a  further 
illustration  of  the  utility  of  nondeterminism,  consider  the 
problem  of  generating  an  arbitrary  permutation  of  a  list  and 
note  the  natural  way  PERMUTE  solves  the  problem  (see 
Figure  1 ,  page  48 ). 

As  an  example  of  a  backtracking  program,  consider  the 
word  RESTRICT  that  solves  the  problem  of  generating  an 
arbitrary  permutation  of  a  list  that  has  predefined  properties 
(we  may  want  the  elements  of  the  list  to  have  a  particular 
order,  or  we  may  require  successive  elements  in  the  list  to  be 
relatively  prime).  For  our  definition  of  RESTRICT,  we  need  to 
assume  we  have  a  word  7PROPERTY  that  tests  the  list  on  the 
data  stack  for  the  particular  property  of  interest,  returning  a 
flag  on  the  stack  indicating  the  result  of  the  test.  Since  we 
have  no  guarantee  that  any  permutation  has  the  necessary 
property,  we  need  to  supplement  our  control  structures  to 
account  for  the  possibility  that  a  sequence  of  choices  made 
during  successive  execution  of  ONEOF  might  result  in  a  list 
without  the  required  property.  To  do  this,  we  add  the  back¬ 
tracking  control  word  NONE.  NONE  is  defined  in  screen  33 
in  Listing  One. 

Execution  of  NONE  restores  the  program  to  the  state  it 
was  in  just  before  execution  of  the  last  ONEOF  and  then 
forces  execution  of  the  word  that  wasn’t  executed  before.  If 
during  execution  of  the  entire  program  a  sequence  of  choices 
(by  ONEOF)  avoids  execution  of  NONE,  we  can  be  sure 
that  sequence  of  choices  will  be  made. 

To  program  for  restricted  permutations,  we  need  only 
define  RESTRICT  as: 


:  RESTRICT  PERMUTE  7PROPERTY  IF  1  ELSE  NONE  0  THEN  ; 


by  L.  L.  Odette 


L.  L.  Odette,  Boston  University,  College  of  Engineering,  Bos¬ 
ton,  Massachusetts  02215. 


As  before,  RESTRICT  expects  the  list  that  will  be  permuted 
to  be  on  the  stack.  By  the  definition  of  NONE,  if  any  permu¬ 
tations  have  the  required  property,  then  one  such  permutation 
will  be  returned. 

Here  again  is  the  expressive  power  of  the  ONEOF. ..NONE 
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control  structure:  We  can  think  in  terms  of  arbitrary  choice, 
knowing  that  a  sequence  of  choices  leading  to  the  desired 
result  will  be  made  if  such  a  sequence  of  choices  can  be  made 
at  all. 

One  way  of  describing  the  use  of  NONE  in  conjunction 
with  ONEOF  is  to  say  that  execution  of  ONEOF  results  in  a 
bifurcation  of  the  Forth  program  and,  in  effect,  creates  two 
Forth  programs  that  are  executed  in  parallel.  If  during  execu¬ 
tion  of  either  program  the  word  NONE  is  executed,  execution 
of  that  program  is  terminated.  A  program  executes  success¬ 
fully  if  it  manages  to  avoid  executing  the  word  NONE.5 

Alternatively,  nondeterministic  control  can  be  viewed  as  a 
form  of  multitasking,  with  ONEOF  randomly  choosing  which 
of  two  tasks  to  run  and  NONE  rescheduling  should  the  run¬ 
ning  task  fail  to  complete. 


Implementation 

To  implement  ONEOF,  provision  must  be  made  for  stor¬ 
ing  the  state  of  the  Forth  machine  at  the  time  ONEOF  is  exe¬ 
cuted.  In  this  implementation,  the  state  of  the  Forth  machine 
consists  of  the  contents  of  the  return  and  data  stacks. 

When  ONEOF  is  executed,  the  top  of  the  return  stack  is 
incremented  by  four  to  point  after  the  next  two  words.  One  of 
the  two  words  following  ONEOF  is  arbitrarily  chosen  for  exe¬ 
cution,  and  a  pointer  to  the  other  is  saved  on  the  return  stack. 
Before  proceeding,  the  contents  of  the  data  and  return  stacks 
are  each  moved  to  the  dictionary  (by  DATA>  and  RETURN>, 
respectively)  in  the  format  SN,  .  .  .  S0,  N  where  N  is  the  stack 
depth  and  SN  is  the  top  stack  entry.  The  stack  depth  is  the  last 
entry  in  the  dictionary.  ONEOF  thus  saves  all  the  information 
necessary  to  backtrack  and  proceed  with  execution  down 
the  other  branch  of  the  program  should  the  word  NONE  be 
encountered. 

Note  that  literals  are  not  allowed  as  the  arguments  (two 
following  words)  of  ONEOF.  In  addition,  variables  must  be 
used  with  care  when  employing  nondeterministic  control, 
since  the  values  of  variables  are  not  saved  and  therefore  will 
not  be  restored  if  NONE  is  encountered. 

ONEOF  and  NONE  resemble  CALL  and  RET  instructions, 
respectively,  the  difference  being  that  ONEOF  is  a  CALL  to  a 
routine  chosen  at  random  from  two  possibilities,  and  NONE  is 
either  a  RET  followed  by  a  call  to  the  other  routine  (the  one 
not  chosen  on  the  last  toss  of  the  coin)  or  a  RET  to  an  even 
higher  level  of  the  main  program  if  both  choices  result  in 
execution  of  NONE.  The  nondeterministic  control  structure 
implemented  with  ONEOF  can  be  nested  arbitrarily  deep 
(limits  on  dictionary  space  will  ultimately  limit  the  nesting 
depth).  It  is  worthwhile  to  note  that  control  structures  may 
be  nested  to  any  depth  in  recursive  calls  and  still  transfer  con¬ 
trol  in  the  correct  manner  on  execution  of  NONE  (see  Figure 
1).  This  is  because  NONE  discards  the  return  stack  entirely, 
recreating  it  exactly  as  it  existed  prior  to  the  last  execution 
of  ONEOF.  ' 

The  result  of  executing  a  word  that  uses  nondeterministic 
control  represents  one  instance  of  all  the  possible  ways  that 
word  may  have  executed.  The  result  of  program  execution  can 
be  described  only  by  a  probability  density  function.  If  more 
than  one  solution  (output)  is  possible,  then  it’s  guaranteed 
that  sometimes  you’ll  get  one  right  answer  and  sometimes 
you’ll  get  a  different  right  answer.  NONE  can  also  be  used  to 
force  execution  of  other  instances  of  a  word,  as  will  be  shown. 

Some  practical  considerations:  The  word  NEW  is  used  to 
reclaim  the  dictionary  space  used  by  ONEOF  for  storage  of 
the  machine  state;  0  is  enclosed  in  the  dictionary  as  a  marker. 
NONE  gives  an  error  message  if  it  finds  the  marker  when  it 
tries  to  restore  the  stacks. 


Example:  N  Queens  Problem 

As  a  final  example  of  the  use  of  a  nondeterministic  control 
structure  in  implementing  backtracking  algorithms,  consider 
the  N  Queens  problem.  The  goal  is  to  determine  the  placement 
of  N  queens  on  an  N  x  N  chessboard  so  that  no  two  queens  are 
in  a  position  to  attack  each  other.  LeVan  published  a  solution 
to  the  8  Queens  problem  to  illustrate  recursion  in  Forth.6  The 
solution  to  the  N  Queens  problem  (See  Figure  2  on  page  50) 
illustrates  the  use  of  nondeterministic  primitives  in  backtrack¬ 
ing  algorithms.  LeVan’s  program  can  be  used  for  comparison. 

The  algorithm  is  straightforward:  A  queen  is  placed  in 
each  of  N  rows  in  turn  so  long  as  no  two  queens  can  attack 
each  other.  If  it  is  impossible  to  place  a  new  queen  so  that  it  is 
not  attacked  by  other  queens  already  on  the  board,  then  the 
program  backtracks  to  try  a  different  placement  of  the  most 
recently  placed  queen.  Nondeterminism  is  introduced  by  the 
use  of  RANDOMN  to  try  a  placement  in  the  current  row. 
NONE  is  executed  if  a  placement  would  imply  attack  by  one 
of  the  queens  already  placed.  ONEOF  and  NONE  are  imple¬ 
mented  so  that,  if  RANDOMN  leads  to  placement  in  row  j  and 
this  in  turn  results  in  execution  of  NONE  (because  a  queen 
placed  in  row  j  can  be  attacked),  row  j  +  1  is  tried  for  the 
placement  of  the  queen.  NONE  thus  results  in  movement  to 
the  right  for  the  most  recently  placed  queen  that  can  be  so 
moved  and  then  forces  the  placement  of  all  subsequent  queens 
to  be  recomputed. 

The  word  QUEENSOLN  returns  a  list  of  the  row  numbers 
on  which  the  queens  are  placed,  for  each  column  from  1  to  N. 
The  predicate  7ATTACKS  is  the  word  most  involved  in  the 
definition  of  QUEENSOLN.  Its  job  is  to  look  at  the  current 
placement  of  the  queens  and  to  decide  whether  the  next  place¬ 
ment  implies  attack  by  one  of  the  queens  already  placed.  All 
information  used  by  7ATTACKS  is  on  the  data  stack  in  the 
form  Rj ,  .  .  .  Rn,  N,  Rn+i  where  N  is  the  number  of  queens 
placed  on  the  board  and  Rj  is  the  row  placement  on  column  j 
of  the  board.  For  each  queen  already  placed,  7ATTACKS  first 
tests  to  ensure  that  placement  of  the  new  queen  is  not  in  the 
same  row.  Possible  attack  along  a  diagonal  is  tested  by  compar¬ 
ing  the  sums  and  differences  of  the  row-column  pairs  for  each 
placement. 

Remember  that  the  list  returned  by  QUEENSOLN  is  only 
one  of  the  possible  solutions.  By  executing  NONE  after  com¬ 
pletion  of  the  program,  another  solution  can  be  computed  and 
displayed.  Figure  2  gives  examples  of  solutions  returned  by 
QUEENSOLN  to  both  the  8  Queens  problem  and  the  12 
Queens  problem.  QUEENSOLN  has  also  been  used  to  find  a 
solution  to  the  14  Queens  problem  (4  9  13  6  2  7  12  1  3  5 
10  8  11  14). 

Discussion 

QUEENSOLN  supports  the  claim  that  nondeterministic 
control  structures  increase  the  expressive  power  of  the  Forth 
language.  Compared  to  the  explicit  programming  of  backtrack¬ 
ing  used  by  LeVan  to  solve  the  8  Queens  problem,  use  of  non¬ 
deterministic  control  yields  a  simpler  program  and  a  more 
natural  expression  of  the  algorithm.  What  is  gained  with  non¬ 
determinism  is  the  ability  to  easily  and  naturally  express  a 
trial -and -error  process.  When  programming,  we  can  concen¬ 
trate  more  on  the  properties  a  solution  must  have  and  less  on 
the  details  of  transferring  control  to  reach  that  solution.  We 
can  write  the  predicates  and  then  think  in  terms  of  arbitrary 
choices,  secure  that  the  correct  sequences  of  choices  will 
eventually  be  made  if  such  a  sequence  exists  at  all.  The  facility 
for  thinking  this  way  is  particularly  useful  when  programming 
searches. 

Keep  in  mind  that  the  use  of  nondeterminism  for  back¬ 
tracking  in  the  N  Queens  problem  is  very  straightforward. 
In  more  complex  problems  involving  many  more  sources  of 
nondeterminism,  a  direct  formulation  in  terms  of  nondeter- 

(Continued  on  page  51 ) 
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SCR  #21 

0  (  L.  L.  Odette  6-2-83  MVP-FORTH  ) 

1  (  Figure  1,  Screen  1  of  2 :  INSERT  and  PERMUTE  words  ) 

2  VARIABLE  LIST-LENGTH 

3 

4  :  SHIFT 

5 

6  :  INVERT 

7 

8 
9 

10 

11  :  + INVERT 

12 

13 

14 

15 
OK 


SCR  #22 

0  (  L.  L.  Odette  6-2-83  MVP-FORTH  ) 

1  (  Figure  1,  Screen  2  of  2:  INSERT  and  PERMUTE  words  ) 

2  :  INSERT 

3 

4 

5 

6 

7 

8 
9 

10  :  PERMUTE 

11 
12 

13 

14 

15 
OK 


0  ,  (  Find  a  random  permutation  of  the  list  on  the  stack  )  OK 
1234567899  PERMUTE  .S  (  List  is  originally  in  order  ) 
4182536979 
OK 

NONE  .S  (  Again  ) 

4812536979 

OK 

NONE  .S  (  Again  ) 

4825316979 

OK 

NONE  .S  (  One  more  time  ) 

4825361979 

OK 

Figure  1. 

Arbitrary  permutation  of  a  list  using  PERMUTE 

The  main  word  in  the  definition  of  permute  in  INSERT,  which  inserts  an  element  X  at  a  random  place  in  a  list  of  length  N. 
The  list  is  assumed  to  be  on  the  stack  in  the  form  X,  XN, . .  .  X1(  N  (top  of  the  stack  to  the  right).  PERMUTE  reduces 
the  list  length  by  1  and  then  calls  itself.  The  return  from  the  recursive  call  uses  INSERT  to  rebuild  the  list  by  inserting  the 
elements  in  random  positions.  PERMUTE  expects  a  list  of  length  N  on  the  data  stack  in  the  form  XN,  XN.j, . . .  X-j,  N. 
The  definition  and  a  description  of  the  word  NONE  is  given  in  the  text. 


DUP  0=  (  Check  to  see  if  list  is  empty  ) 

IF  1+  (  Add  new  member  if  empty  ) 

ELSE  INVERT  1-  (  Insert  latest  in  list-last  ) 

ONEOF  + INVERT  (  Insert  latest  at  end  ) 

MYSELF  1+  (  Or  recurse  ) 

THEN  ; 


DUP  IF  1-  MYSELF  INSERT  THEN  ; 


LIST-LENGTH  @  ROLL  ;  (  Rotate  list  on  stack  ) 

DUP  2+  LIST-LENGTH  !  (  Initialize  data  length  ) 
SHIFT  SHIFT  SWAP  (  Rotate  last,  latest  to  top  ) 

3  PICK  0  (  Set  loop  limits  ) 

DO  SHIFT  LOOP  ;  (  Last  and  latest  reversed  ) 

1+  INVERT  ; 
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SCR 

#34 

0 

(  L.  L.  Odette  6-2-83 

MVP-FORTH  ) 

1 

(  Figure  2  , 

Screen  1  of  2:  8  Queens  Problem  ) 

2 

VARIABLE  BVAR 

(  Boolean  Variable  ) 

3 

4 

:  TRUE  DROP  1  BVAR  !  ; 

(  Set  Boolean  true  ) 

5 

:  7ATTACKS 

0  BVAR  !  OVER 

(  Init  Boolean  false  ) 

6 

IF  OVER  0 

7 

DO  OVER  1-2+  PICK 

(  Get  row  placement  ) 

8 

OVER  OVER  = 

(  In  same  row  7  ) 

9 

IF  TRUE  LEAVE 

(  Yes  -  attack  possible  ) 

10 

ELSE  OVER  4  PICK  - 

OVER  I  -  =  (  Diagonal?  ) 

11 

IF  TRUE  LEAVE 

(  Yes  -  attack  possible  ) 

12 

ELSE  OVER  4  PICK 

+  OVER  I  +  =  (  Diagonal?  ) 

13 

IF  TRUE  LEAVE 

ELSE  DROP  THEN 

14 

THEN  THEN 

15 

LOOP  THEN  BVAR  @  ; 

(  Leave  flag  on  stack  ) 

OK 

SCR 

#35 

0 

(  L.  L.  Odette  6-2-83 

MVP-FORTH  ) 

1 

(  Figure  2, 

Screen  2  of  2:  8  Queens 

Problem  ) 

2 

*3 

:  RANDOMN 

DUP  IF  1-  ONEOF  MYSELF 

1+  THEN  ; 

■j 

4 

:  TRYQUEEN 

DUP  2+  PICK  RANDOMN  ; 

(  Choose  a  row  placement) 

5 

:  ADDQUEEN 

SWAP  1+  ; 

(  Add  row  placement  ) 

6 

:  7LASTQUEEN  DUP  2+  PICK  OVER  < 

(  Check  column  count  ) 

7 

7TERMINAL  IF  DROP  1  THEN  ;  (  Check  keyboard  too  ) 

8 

:  PRINTSOL 

CR  DUP  4  .R  . "  QUEENS" 

(  Print  row  placement  ) 

9 

0  DO  1+  4  .R  LOOP  DROP 

4  SPACES  ; 

10 

11 

:  QUEENSOLN 

1-  0 

12 

BEGIN  TRYQUEEN 

13 

7ATTACKS  IF  NONE  ELSE  ADDQUEEN  THEN 

14 

7LASTQUEEN  UNTIL 

15 

PRINTSOL  ; 

OK 

0  , 

8  QUEENSOLN 

(  Solves  for  8  Queens  - 

0  indicates  dictionary  end  ) 

8 

QUEENS  8 

3  1  6  2  5  7 

4  OK 

NONE 

(  Backtrack  to  find  a  different  solution  ) 

8 

QUEENS  2 

8  6  1  3  5  7 

4  OK 

NONE 

(  More  ) 

8 

QUEENS  6 

1  5  2  8  3  7 

4  OK 

NONE 

(  More  ) 

8 

QUEENS  3 

6  2  5  8  1  7 

4  OK 

NONE 

(  Even  more  ) 

8 

QUEENS  6 

3  7  2  8  5  1 

4  OK 

NEW 

(  Reclaim 

dictionary  )  OK 

0  , 

L  2  QUEENSOLN 

(  Solves  for  12  Queens 

!  ) 

12 

QUEENS  9 

4  6  11  2  7  1 

3  5  81012  OK 

NONE 

(  More  ) 

12 

QUEENS  7 

4  6  11  9  1  3 

5  2  81012  OK 

Figure  2. 

Solution  of  the  N  Queens  problem  using  QUEENSOLN 

QUEENSOLN  expects  the  hoard  size  N  on  the  stack  and  returns  a  list  of  N  row  placements  for  N  queens  in  the  columns  from 

1  to  N.  Execution  of  NONE  will  result  in  backtracking  and  the  computation  of  a  new  solution.  The  word  NEW  is  used  to 

reclaim  the  dictionary  space  used  by  ONEOF. 
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(Confined  from  page  46) 

ministic  primitives  provides  significant  advantages  over  explicit 
programming  of  backtracking.  The  advantages  of  nondetermi¬ 
nism  are  also  apparent  for  implementing  various  randomizing 
algorithms,  such  as  the  random  permutation  program  of 
Figure  1. 

Purists  will  note  that  there  is  no  such  thing  as  random 
choice  operating  in  any  of  the  programs  we  have  discussed. 
This  is  because  we’ve  used  a  pseudo  random  number  generator 
in  the  definition  of  ONEOF  to  determine  where  to  transfer 
control.  In  fact,  each  time  ONEOF  is  executed,  transfer  of 
control  is  determined  entirely  by  the  state  of  the  pseudo  ran¬ 
dom  number  generator  (the  contents  of  the  variable  RND; 
see  screen  30  in  Listing  One). 

Notwithstanding  this  technicality,  ONEOF  and  NONE 
work  quite  well.  One  of  the  more  interesting  effects  is  that 
QUEENSOLN  takes  different  times  to  run  on  successive  exe¬ 
cutions.  Observations  of  this  sort  are  reasons  why  probabilistic 
algorithms  are  an  intriguing  area  for  research.  For  example, 
keeping  in  mind  that  the  randomness  is  not  in  the  input  data 
but  in  the  way  the  program  executes,  we  might  ask  the  follow¬ 
ing  question:  Given  a  deterministic  algorithm  that  takes  a  cer¬ 
tain  time  to  run  to  completion,  can  a  probabilistic  algorithm 
be  created  that  has  a  faster  mean  time  to  solution? 
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Nondeterministic  Control  -  Listing 


(Text  begins  on  page  44) 

SCR  #30 

0  (  L.  L.  Odette  6-2-83 

X 

2  VARIABLE  RND  HERE  RND  ! 


MVP-FORTH  ) 
(  Random  Number  Words  ) 


:  RANDOM  RND  @  31421  *  6927  +  DUP  RND  !  ; 

:  CHOOSE  RANDOM  0*  SWAP  DROP  ; 

:  MYSELF  LATEST  PFA  CFA  ,  ;  (  Control  word  for  recursion  ) 

IMMEDIATE 

:  NEW  -2  ALLOT  HERE  @  (  Dictionary  Reclaimation  ) 

IF  BEGIN  HERE  @  2+  NEGATE  ALLOT 
HERE  @  0= 

UNTIL 
THEN  ; 


#31 

(  L.  L.  Odette 


6-2-83 


MVP-FORTH  ) 


(  Words  used  to  save  and  restore  the  data  stack  ) 


SP@  DUP  SO  SWAP  -  DUP  (  Get  length  in  bytes  ) 

ROT  HERE  ROT  CMOVE  (  Move  to  dictionary  ) 

DUP  ALLOT  ,  ;  (  Adjust  dictionary  pointer  ) 


-2  ALLOT  SO  DUP  >R 
HERE  @  -  SPO  !  SP! 

R>  SPO  I 

SP@  HERE  @  DUP 

NEGATE  ALLOT 

HERE  ROT  ROT  CMOVE  ; 


(  Save  initial  stack  address  ) 

(  Reset  stack  pointer  ) 

(  Reset  initial  stack  address  ) 
(  Get  address  for  move  ) 

(  First  adjust  disctionary  ) 

(  Restore  data  stack  ) 


132 

(  L.  L.  Odette 


6-2-83 


MVP-FORTH  ) 


(  Words  used  to  save  and  restore  the  return  stack  ) 

:  RETURN>  RP@  2+  R0  @  OVER  -  (  Calculate  length  in  bytes  ) 

DUP  ROT  HERE  ROT  CMOVE  (  Ret-stack  to  dictionary  ) 

DUP  ALLOT  ,  ;  (  Adjust  dictionary  pointer  ) 


R>  -2  ALLOT 
R0  @  DUP  HERE  @  - 
R0  1  RP!  R0  1 
HERE  @  DUP 
NEGATE  ALLOT 
HERE  RP@  ROT  CMOVE 
>R  » 


(  Save  top  of  return  stack  ) 

(  Compute  stack  pointer  ) 

(  Reset  stack  pointer  ) 

(  Adjust  dictionary  pointer  ) 
(  Restore  return  stack  ) 

(  Restore  old  top  of  stack  ) 


SCR  #33 


(  L.  L.  Odette  6-2-83 
(  ONEOF  and  NONE  control  words  ) 


MVP-FORTH  ) 


<ONEOF> 


R>  DUP  4  +  >R 
DUP  2  CHOOSE 
IF  2+  >R 
ELSE  >R  2+  THEN 
RETU  RN> 

R>  DROP  >R 
DATA> 

R>  @  EXECUTE  ; 
COMPILE  <ONEOF> 


(  Increment  return  pointer  ) 
(  Toss  coin  ) 

(  Save  pointer  to  first  ) 

(  or  second  word  ) 

(  Copy  return  stack  ) 

(  Juggle  pointers  ) 

(  Copy  data  stack  ) 

(  Execute  one  not  saved  ) 
IMMEDIATE 


HERE  2-  @  (  Test  data  length  ) 

IF  >DATA  >RETURN  R>  @  EXECUTE  (  Restore  and  continue) 
ELSE  CR  ***End  of  data***  "  THEN  ; 


End  Listing 
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GO  in  Forth 


Dr.  Jonathan  K.  Millen  published  a 
very  interesting  article  on  “Pro¬ 
gramming  the  Game  of  Go”  in  the 
April  issue  of  Byte  magazine  in  1981.  It 
was  a  milestone  in  the  computerization  of 
this  ancient  Chinese  board  game.  There 
were  two  major  contributions  in  this 
work.  First  was  the  very  simple  algorithm 
for  analyzing  the  progress  of  the  game  by 
counting  the  liberties  of  connected  groups 
of  stones.  The  liberty  count  became  the 
priority  scale  that  could  be  used  to 
decide  the  next  move  by  the  computer. 
Second  was  the  demonstration  that, 
using  this  approach,  a  very  small  micro¬ 
computer  could  be  programmed  to  play 
the  Go  game,  which  had  always  been 
considered  to  be  too  complicated  for 
small  computers. 

This  simple  algorithm  cannot  cope 
very  satisfactorily  with  all  the  intricacies 
of  Go;  however,  it  does  provide  a  very 
firm  foundation  for  future  improvements 
and  embellishments.  The  fact  that  Millen’s 
program  is  capable  of  playing  legitimate 
games,  with  only  minor  exceptions,  dem¬ 
onstrates  well  that  his  algorithm  captured 
the  most  essential  features  of  the  game.  It 
forms  a  backbone  of  advanced  Go  pro¬ 
grams  in  which  other  features  can  be 
added  readily  to  deal  with  tactics  and 
strategy. 

1  took  Dr.  Millen’s  article  as  a  chal¬ 
lenge  to  a  programmer’s  skill  to  implement 
it  on  a  small  computer.  His  implementa¬ 
tion  was  on  a  KIM-1  with  1  Kbyte  of 
memory.  The  response  time  for  a  move 
was  about  one  second.  These  features  are 
hard  to  match.  It  would  be  interesting  to 
see  if  it  could  be  put  on  other  computers, 
preferably  in  a  high-level  language  to 
make  the  program  transportable.  Forth 
was  chosen  because  of  its  compactness 
and  efficiency  in  both  programming  and 
runtime.  This  game  was  programmed  and 
used  as  both  a  practical  example  and  a 
teaching  example  of  the  Forth  language  in 
late  1981.  when  I  was  back  in  Taiwan 


by  C.  H.  Ting 


C.  H.  Ting,  Offete  Enterprises,  1306  South 
B  Street,  San  Mateo,  California  94402. 

Copyright  ©  1982,  1983  by  C.  H.  Ting. 
All  rights  reserved. 

Permission  is  granted  for  personal,  non- 
commerical  use  only.  Any  use  for  profit 
or  other  commercial  gain  without  written 
permission  of  the  author  is  prohibited. 


trying  to  preach  the  gospel  of  Forth.  It 
was  very  effective  because  the  difficulty 
in  this  game  was  well  understood  over 
there.  A  working  Go  game,  in  spite  of  its 
shortcomings,  was  impressive. 

The  Algorithm 

The  algorithm  to  play  the  game  of 
Go  as  published  by  Dr.  Millen  is  shown  in 
Figure  1  (page  55).  For  a  more  detailed 
description  of  the  mechanism  and  ration¬ 
ale  in  this  program,  the  interested  reader 
should  consult  the  original  article.  How¬ 
ever,  the  structured  English  he  used  to 
express  the  algorithm  is  not  difficult  to 
comprehend. 

Implementation 

The  program  was  first  developed  on 
an  LSI-11  microcomputer  with  Poly-Forth 
as  the  operating  system.  The  source  code 
spans  8  Kbytes,  though  loosely  packed. 
The  compiled  code,  including  362  bytes 
to  hold  the  complete  19-by-19  board, 
occupied  about  3  Kbytes.  The  response 
time  for  a  move  is  about  seven  seconds. 

Later,  after  I  had  finished  a  Forth-79 
system  for  the  Apple  II  and  had  succeeded 
in  putting  Forth  in  PROMs  (replacing  the 
Applesoft  BASIC  chip  set),  I  tried  to 
transfer  the  Go  game  into  the  Apple. 
Since  the  source  code  is  less  than  8  Kbytes, 
it  was  burned  into  four  2716’s  and  moved 
into  the  Apple  on  an  Apple  ROM  card. 
The  Forth  system  in  the  Apple  compiles 
the  source  code  in  ROM  to  object  code 
stored  in  RAM  and  executes  the  Go  game. 
The  interesting  thing  about  this  scheme  is 
that  I  can  run  a  number  of  games  with 
the  same  Apple,  with  all  the  games  on 
ROM  cards  in  source  form. 

Transportability 

To  make  sure  that  the  program  can 
be  transported  to  other  microcomputers, 
it  is  important  to  avoid  memory-mapped 
graphic  representation  of  the  Go  board. 
Standard  terminal  I/O  commands  are 
used  to  draw  the  board  with  stones  on 
the  CRT  screen.  The  only  terminal- 
dependent  commands  are  HOME  and 
EOL  (HOME  returns  the  cursor  to  the 
upper  left  corner  of  the  screen  and  EOL 
erases  a  line  of  characters).  These  two 
commands  manage  a  stationary  board  on 
the  screen  and  facilitate  the  key-in  of  the 
player’s  moves.  They  are  not  necessary  if 
one  does  not  mind  the  scrolling  of  the 
game  board. 

Although  Forth-79  standard  was 
used  to  present  the  program,  it  can  be 


readily  modified  to  fig-Forth  or  other 
Forth  systems.  In  fact,  I  have  seen  the 
program  running  on  a  couple  of  CP/M 
fig-Forth  systems,  some  of  which  I  imple¬ 
mented  for  local  computer  manufacturers 
in  Taipei  for  demonstration  purposes. 

The  Board 

Let  us  turn  to  the  source  screens  in 
Listing  One  (page  63)  to  see  how  the  al¬ 
gorithm  is  implemented. 

The  first  two  lines  in  screen  160 
declare  some  constants  and  variables. 
BLACK  is  the  code  of  black  stones, 
having  a  constant  value  of  1.  Similarly, 
WHITE  has  a  constant  value  of  2.  COL¬ 
OR  is  a  variable  used  to  transfer  the  code 
of  the  stone  groups  currently  under  proc¬ 
essing.  LIBERTY  is  the  liberty  count 
(discussed  below)  accumulated  for  a 
group  of  connected  stones;  this  is  the 
primary  indicator  of  the  priority  for 
attention  to  a  given  group  of  stones.  MAP 
is  an  array  of  362  bytes,  storing  the  cur¬ 
rent  board  configuration.  Each  location 
on  the  19 -by -19  grid  is  designated  as  a 
byte  in  this  array.  A  zero  in  a  byte  indi¬ 
cates  an  empty  grid  location,  a  1  indicates 
a  black  stone,  and  a  2  indicates  a  white 
stone. 

Skipping  the  rest  of  screen  160,  let  us 
look  at  the  source  code  in  screen  161,  be¬ 
cause  it  deals  with  the  display  of  the 
game  board.  HOME  moves  the  cursor  to 
the  upper  left  comer  of  the  screen,  pre¬ 
paring  to  write  the  new  board  configura¬ 
tion  over  the  old  board.  It  is  desirable  to 
keep  an  image  of  the  old  board  on  the 
screen.  HOME  is  written  in  assembly 
code,  calling  the  Apple  Monitor  routine 
to  do  the  trick. 

BK,  WT,  and  CROSS  respectively 
print  a  black  stone,  white  stone,  or  grid 
cross  point  on  the  screen.  A  black  stone 
is  the  “@”  character.  A  white  stone  is 
the  capital  “O.”  The  grid  crossing  was 
first  represented  by  the  “+”  sign,  but 
later  replaced  by  the  period  because  the 
“+”  signs  are  too  heavy  and  tend  to 
obscure  the  stones  on  the  CRT  screen. 

LIMITS  places  two  numbers,  361  and 
0,  on  the  stack  because  they  are  often 
used  to  designate  the  loop  limits  in  the 
analysis  of  board  positions. 

INDEX  prints  a  line  of  indices  on 
the  top  of  the  board  to  designate  the  col¬ 
umns  of  the  board.  BOARD  prints  the 
complete  board  on  the  screen,  with  indices 
on  top  and  left.  It  takes  the  contents  of 
the  array  MAP  and  prints  the  appropriate 
stones  on  the  board.  The  MAP  array  is 
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initialized  by  CLRMAP,  which  erases  the 
array  to  zeros. 

PLACE  stores  a  code  into  one  of  the 
array  elements.  The  top  of  stack  has  the 
board  position;  the  next  item  is  the  code 
to  be  stored  in  that  location.  KSTONE 
removes  a  stone  from  the  board  by  stor¬ 
ing  a  zero  in  the  corresponding  array 
element.  These  two  commands  change 
the  board  configuration.  PUT  is  a  utility 
to  put  a  contiguous  block  of  stones  on 
the  board  for  testing  purposes.  The  color 
of  the  stones  is  specified  by  the  contents 
of  COLOR. 

Base  19  Numbering  System 

GOBASE  stores  19  into  the  user  vari¬ 


able  BASE,  specifying  that  all  subsequent 
number  conversions  are  to  be  done  in 
base  19.  This  is  the  most  appropriate 
number  base  for  the  Go  game,  since  it  is 
played  on  a  19-by-19  board.  The  advan¬ 
tage  in  using  base  19  is  that  all  rows  and 
columns  can  be  designated  with  one  char¬ 
acter  from  0  to  9  and  A  to  J.  When  typ¬ 
ing  in  a  move,  the  player  can  type  one 
number  —  e.g.,  35,  AF,  9J,  etc.  —  to  rep¬ 
resent  a  board  location.  This  number  is 
the  exact  offset  to  pick  up  the  proper 
array  element  in  MAP,  without  any  com¬ 
plicated  conversions.  The  freedom  in 
choosing  the  best  number  base  for  a  spe¬ 
cific  application  is  a  luxury  only  a  Forth 
programmer  can  enjoy. 


A  very  good  example  of  how  to  use 
GOBASE  is  the  command  HANDICAP, 
which  places  nine  handicap  stones  on  the 
board  to  give  the  computer  a  fighting 
chance  to  compete  with  a  human  player. 
After  switching  the  base  to  19  via  GO- 
BASE,  the  board  positions  can  be  conven¬ 
iently  specified  as  33,  3A,  3F,  etc.,  and 
PLACEd  on  the  board  in  a  short  loop. 
After  HANDICAP,  the  base  is  returned 
to  decimal  for  normal  processing. 

Liberty  Counts 

The  most  important  procedure  in 
Millen’s  algorithm  is  that  which  scans  a 
group  of  connected  stones  of  the  same 
color,  and  counts  the  liberties,  or  the 


Listing  1:  Structured  English  specifications  of  COUNT  module 

IF  the  group  has  1  or  2  liberties 

to  find  and  count  the  liberties  of  a  connected  group  containing 

THEN  CALL  EVAL  for  the  chosen  liberty 

a  stone  at  point  "x"  of  color  "color."  COUNT  calls  itself  re- 

END 

cursively,  saving  x  on  the  push -down  stack  during  each  call. 

END 

COUNT ( x,  color) : 

BEFFECT: 

1 F  x  is  not  off  the  edge 

FOR  each  point  x  with  a  white  stone  DO 

THEN 

CALL  COUNTlx, white) 

IF  there  is  a  stone  at  x  AND 

IF  the  group  has  exactly  1  liberty 

it  is  the  given  color  AND 

THEN 

it  is  not  marked 

designate  it  as  the  black  move 

THEN 

remove  the  white  stones 

mark  it 

EXIT 

CALL  COUNTINORTH(x),  color) 

ELSE  IF  the  group  has  2  or  more  liberties 

CALL  COUNT ( EAST (x),  color) 

THEN 

CALL  COUNT(SOUTHIx), color) 

choose  a  liberty 

CALL  COUNTlWEST(x),  color) 

CALL  EVAL  for  the  chosen  liberty 

ELSE  IF  there  is  no  stone  at  x 

END 

THEN 

END 

mark  the  point  as  a  liberty 

increment  the  liberty  count 

END 

END 

Listing  3:  Module  specifications  for  move  evaluation,  look- 

ahead,  and  pattern  matching. 

EVAL  (move, liberties): 

GLOBAL  (best-move,  best-liberties) 

1 F  liberties  ^  best -liberties  AND 

Listing  2:  Module  specification  for  the  main  loop  of  the  Go- 

LOOKAHEAD(move)>  2 

playing  program  and  two  of  its  called  modules. 

THEN 

best -move  =  move 

MAIN : 

best -liberties  =  liberties 

place  black  handicap  stones 

END 

LOOP 

display  the  board 

LOOK  AH  EAD  (move) : 

get  white's  move  from  keyboard 

place  black  stone  at  move 

CALL  WEFFECT  for  the  effect  of  white's  move 

CALL  COUNT  (move .black) 

CALL  BEFFECT  to  obtain  a  tentative  black  move 

CALL  PATS  to  check  for  a  pattern  match 

RETURN  count  of  liberties 

place  black  stone 

END 

PATS: 

FOR  each  white  stone  DO 

WEFFECT: 

IF  there  is  a  pattern  in  the  table 

FOR  each  point  x  with  a  black  stone  DO 

centered  on  that  white  stone 

CALL  COUNT (x,black ) 

THEN 

IF  the  group  has  no  liberties 

get  suggested  black  move  y 

THEN  remove  its  stones 

CALL  EVAL(y,2) 

ELSE  IF  the  group  has  at  least  one  liberty 

EXIT 

THEN 

END 

choose  a  liberty  not  on  edge  line 

END 

Figure  1. 

From  "Programming  in  the  Game  of  Go"  by  Jonathan  Millen,  originally  published  in  the  April  1981  issue  of  Byte  magazine. 

Used  with  the  written  permission  of  Jonathan  K.  Millen. 
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open  grid  positions,  around  this  group. 
This  procedure  is  implemented  in  screen 
160. 

Let  us  follow  the  order  in  which 
commands  are  defined  in  screen  160. 
?OUT  takes  the  number  at  the  top  of  the 
stack  and  checks  its  range.  If  the  number 
is  between  0  and  360  inclusive,  a  false 
flag  is  returned;  otherwise,  a  true  is  re¬ 
turned.  It  will  be  used  to  abort  a  count¬ 
ing  procedure  if  the  stone  location  is 
outside  of  the  board. 

?STONE  merely  returns  the  code  of 
the  stone  whose  location  is  given  on  the 
top  of  the  stack.  The  top  of  stack  number 
is  used  as  an  offset  into  the  MAP  array  to 
pick  up  the  code  stored  in  the  specified 
location. 

NORTH,  SOUTH,  EAST,  and  WEST 
are  the  commands  that  convert  the  cur¬ 
rent  stone  location  on  top  of  the  stack  to 
the  neighboring  location  in  the  direction 
indicated  by  the  names  of  the  commands. 
The  returned  location  might  be  outside 
of  the  board,  as  NORTH  and  SOUTH 
would  do  if  the  given  location  is  at  the 
edge  of  the  board.  In  the  cases  of  EAST 
and  WEST,  there  is  the  problem  of  hori¬ 
zontal  wrap-around.  If  the  current  loca¬ 
tion  is  at  the  left  edge,  WEST  will  then  re¬ 
turn  the  number  1000,  which  is  definitely 
outside  of  the  board.  EAST  will  do  like¬ 
wise  at  the  right  edge. 

MARK  sets  the  most  significant  bit 
of  the  code  whose  location  is  on  the  top 
of  the  stack.  This  command  puts  a  mark 
on  the  locations  that  were  scanned  at 
least  once  so  that  the  location  will  not 
be  repeatedly  scanned  or  repeatedly 
counted. 

RECUR  is  the  famous  Fig-Forth 
command  allowing  compilation  of  recur¬ 
sive  procedures.  (Other  versions  of  Forth 
may  use  other  words,  such  as  MYSELF  or 
RECURSE.)  It  compiles  the  code  field 
address  of  the  procedure,  which  is  still 
in  the  process  of  compilation,  allowing  it 
to  call  itself  at  runtime. 

COUNTS  walks  through  an  entire 
group  of  connected  stones  and  accumu¬ 
lates  its  liberties  in  the  variable  LIBERTY. 
The  color  of  the  stone  group  is  specified 
in  the  variable  COLOR.  It  walks  by  the 
left-turn  rule  of  the  maze  theorem,  ex¬ 
amining  the  locations  north,  east,  south, 
and  west  of  the  current  location.  If  that 
neighboring  location  has  an  unmarked 
stone  of  the  same  color,  it  will  jump  into 
this  location  and  call  itself  to  continue 
the  walking.  It  will  increment  the  LIBER¬ 
TY  count  if  the  neighboring  location  is 
empty  and  unmarked.  It  marks  every 
location  it  examines  so  that  locations  will 
not  be  repeatedly  scanned  or  counted.  At 
the  end  of  this  recursive  process,  all  the 
connected  stones  of  the  same  color  will 
have  been  scanned  and  all  the  liberties 
around  this  group  will  have  been  marked 
and  counted. 

The  recursive  procedure  is  naturally 


limited  in  its  depth  by  the  sizes  of  the 
stacks  allocated  by  the  system.  In  this  im¬ 
plementation  each  level  of  call  uses  one 
cell  of  the  return  stack  and  one  cell  of  the 
data  stack.  Since  in  most  Forth  systems 
the  return  stack  has  about  256  bytes, 
COUNTS  can  process  a  group  of  100 
connected  stones.  This  is  adequate  for 
most  games  normally  played.  The  system 
will  crash  if  the  stacks  overflow. 

Removing  Stones 

In  screen  162,  the  important  com¬ 
mands  are  DESIGNATE  and  REMOVE. 
DESIGNATE  is  to  be  used  in  the  case 
that  a  group  of  white  stones  has  only  one 
liberty  left.  The  computer  will  immedi¬ 
ately  kill  this  group  by  playing  a  black 
stone  into  the  liberty.  After  the  counting 
process,  this  liberty  location  is  the  only 
location  having  a  code  of  128,  empty  and 
marked.  DESIGNATE  simply  scans  the 
board,  and  upon  finding  this  location, 
plays  the  killing  move. 

REMOVE  erases  an  entire  connected 
group  of  stones,  whose  color  is  designated 
in  COLOR.  REMOVE  is  very  similar  to 
COUNTS,  using  the  same  recursive  tech¬ 
nique  to  scan  the  connected  group.  It 
marks  the  member  stones  in  the  group  by 
setting  the  seventh  bit  of  the  code  as  the 
kill  mark,  so  that  the  stone  scanned  will 
be  deleted  at  the  end  of  the  REMOVE 
process.  KMARK  performs  this  marking 
task. 

After  the  counting  or  the  removing 
process,  many  locations  examined  are 
tagged  by  the  counting  marks  or  the  kill 
marks.  To  continue  the  processing  of 
other  stone  groups,  these  marks  must  be 
removed  to  restore  the  board  map  to  a 
clean  state.  This  is  accomplished  by  the 
command  UNMARK.  UNMARK  scans 
through  the  whole  board  and  resets  all 
the  bits  in  the  codes  according  to  the 
reset  pattern  given  on  the  top  of  the  stack. 
This  way,  it  can  be  used  to  selectively 
reset  either  the  counting  bits,  the  kill  bits, 
or  both  at  the  same  time. 

Lookahead 

This  Go  program  only  has  the  ability 
to  look  ahead  by  one  step,  which  is  one 
of  its  many  weaknesses.  However,  one-step 
lookahead  does  give  it  some  similarity  to 
an  amateur  player.  Screen  163  contains 
the  commands  to  examine  the  board  con¬ 
figuration  one  step  ahead. 

The  variables  BEST-MOVE,  BEST- 
LIBERTIES,  BEST-COUNT,  and  !COL- 
OR  are  temporary  storage  locations 
used  to  determine  the  best  move  in  a 
given  board  configuration.  The  command 
LOOKAHEAD  takes  a  board  location 
given  on  the  top  of  the  stack,  tentatively 
places  a  black  stone  in  this  location,  and 
counts  the  liberties  around  the  group  of 
black  stones  connected  to  this  stone.  The 
liberty  count  is  returned  to  the  stack,  and 
the  black  stone  is  removed  from  this  loca¬ 


tion.  A  better  move  for  the  black  would 
have  a  larger  liberty  count.  The  liberty 
count  is  then  compared  to  that  in  the 
BEST-LIBERTIES  to  decide  whether 
BEST-MOVE  needs  to  be  updated  in  the 
later  command. 

EVAL  does  the  comparison  and  up¬ 
dating.  It  takes  two  values  off  the  stack; 
the  top  value  is  the  maximum  liberty 
count  allowed  in  the  current  configura¬ 
tion  and  the  second  is  the  move  to  be 
examined.  EVAL  calls  LOOKAHEAD  to 
get  the  liberty  count  of  the  proposed 
move.  If  the  resulting  liberty  count  is 
greater  than  the  count  in  BEST-COUNT, 
and  the  maximum  count  given  on  the 
stack  is  not  greater  than  the  count  in 
BEST-LIBERTIES,  the  proposed  move 
should  be  a  better  choice  than  the  one 
indicated  in  BEST-MOVE  as  the  result 
of  prior  analysis.  In  this  case  the  variables  - 
BEST-MOVE,  BEST-COUNT,  and  BEST- 
LIBERTIES  are  updated.  Otherwise,  the 
best  move  as  determined  by  prior  analysis 
remains  intact. 

Going  through  this  evaluation  proc¬ 
ess  for  all  the  black  groups,  the  computer 
will  be  able  to  pick  up  the  weakest  black 
group  and  find  the  best  move  to  maxi¬ 
mize  its  liberty  count;  hopefully  this  will 
save  the  black  group  from  being  captured 
by  the  white  stones.  In  attacking  the 
weakest  white  group,  it  also  chooses  the 
most  secured  move  so  that  the  attacking 
stone  will  not  be  threatened  easily. 

Pattern  Recognition 

The  following  two  screens,  164  and 
165,  contain  commands  dealing  with 
some  elementary  pattern  recognition, 
designed  to  identify  some  favorable  posi¬ 
tions  to  be  considered  in  the  evaluation 
process.  Dr.  Millen  identified  seven  pat¬ 
terns  in  which  a  designated  black  move 
usually  improves  on  the  overall  black 
configuration.  These  seven  patterns,  in¬ 
cluding  some  permutations  and  reflec¬ 
tions,  are  reduced  to  twelve  16-bit  pat¬ 
terns  stored  in  an  array  named  PATTERN. 
The  coding  scheme  is  illustrated  in  Fig¬ 
ure  2  (page  59).  An  empty  location  will 
be  examined  by  coding  the  stone  distri¬ 
butions  in  the  neighboring  3-by-5  regions 
to  its  immediate  north,  east,  south,  and 
west.  If  any  of  the  four  codes  matches 
with  one  of  the  twelve  patterns,  this 
empty  location  is  assigned  a  liberty  count 
value  of  2,  a  rather  high  priority. 

?  RANGE  takes  a  board  location  off 
the  stack  and  returns  the  code  stored  in 
the  location.  The  difference  from  7STONE 
is  that  if  the  location  is  outside  of  the 
board,  7RANGE  will  return  a  1,  the  code 
for  black  stone.  This  is  the  “ghost  stone” 
asserted  by  Dr.  Millen.  The  entire  board 
can  be  considered  as  being  surrounded  by 
black  stones  to  take  into  account  some 
favorable  conditions  near  the  edges  of  the 
board. 

Given  a  particular  board  location, 
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?N,  ?E,  ?S,  and  ?W  return  the  code  of  its 
northern,  eastern,  southern,  and  western 
neighbor,  respectively.  They  use  ?  RANGE 
to  find  the  codes.  If  the  neighbor  is  off 
the  board,  the  code  of  a  black  stone  will 
be  returned. 

+4*  is  a  strange  command  that 
generates  a  16 -bit  code  according  to  the 
rules  for  the  codes  being  constructed  in 
PATTERN.  It  takes  eight  items  off  the 
stack  and  packs  the  least  significant  two 
bits  in  each  item  into  a  16 -bit  code,  to  be 
left  on  the  stack.  These  items  are  the 
codes  of  stones  immediately  around  a 
location,  and  their  order  on  the  stack  is 
according  to  the  sequence  specified  in 
Figure  1 . 

PNORTH  is  given  a  specific  location 
on  the  stack  and  looks  at  its  northern 
neighboring  location.  If  this  neighbor  is 
empty,  PNORTH  will  walk  through  its 
eight  neighboring  locations,  push  their 
codes  of  stones  on  the  stack,  and  call  +4* 
to  pack  these  eight  codes  into  a  single 
16-bit  pattern  code.  However,  if  the 
northern  neighbor  is  not  empty,  PNORTH 
will  exit  immediately  because  this  neigh¬ 
boring  location  is  not  playable  and  does 
not  need  pattern  matching. 

PEA  ST,  PSOUTH,  and  PWEST  behave 
similarly.  It  seems  rather  clumsy  that  four 
similar  words  have  to  be  defined  to  do 
very  similar  tasks.  Some  better  tools  are 


needed  here  to  clean  up  the  codes. 

MATCH  is  the  command  that  does 
the  pattern  matching.  It  takes  a  coded 
pattern  off  the  stack  and  compares  it 
with  the  patterns  stored  in  PATTERN.  If 
the  coded  pattern  matches  with  one  of 
the  stored  patterns,  a  true  flag  is  left  on 
the  stack;  otherwise,  a  false  flag  is  left. 
The  big  command  PATS  scans  the  whole 
board  looking  for  white  stones.  Finding 
a  white  stone,  PATS  will  use  PNORTH, 
PEAST,  PSOUTH,  and  PWEST  to  exa¬ 
mine  its  surroundings  to  see  if  a  stored 
pattern  could  be  identified.  It  will  abort 
the  loop  at  the  first  sight  of  a  matched 
pattern,  assign  a  priority  of  2  to  this 
pattern,  and  call  EVAL  to  do  an  evalua¬ 
tion.  Since  PATS  is  the  last  pass  in  the 
evaluation  process,  its  finding  is  preferred 
over  other  evaluations  of  the  same 
priority. 

In  matching  a  coded  pattern  with  the 
stored  patterns,  I  initially  used  the  com¬ 
parison  command  =  to  match  the  pat¬ 
terns.  This  turned  out  to  be  a  very  restric¬ 
tive  operation  because  among  the  eight 
neighbors  there  are  two  or  three  con¬ 
sidered  to  be  crucial  —  the  others  can  be 
ignored.  FIX  takes  the  coded  pattern  and 
ANDs  it  with  the  stored  pattern  to  elimi¬ 
nate  the  non-crucial  bits  in  the  coded 
pattern.  The  resulting  modified  pattern 
is  then  compared  with  the  stored  pattern 


to  determine  a  match.  However,  adding 
FIX  to  MATCH  tends  to  make  the  com¬ 
parison  too  liberal.  It  is  probably  neces¬ 
sary  to  define  a  set  of  masks  to  be  used 
together  with  the  patterns  in  order  to  be 
able  to  precisely  identify  the  desired 
patterns. 

Analysis 

Screen  166  hosts  the  two  major  anal¬ 
ysis  routines:  WEFFECT,  which  analyzes 
the  effects  of  the  white  stones,  and  B- 
EFFECT,  which  analyzes  the  effects  of 
the  black  stones.  The  variable  ?STOP 
and  the  command  STOP  (which  clears 
7STOP)  will  be  used  later  in  the  main 
loop  to  bypass  the  pattern  recognition 
process  if  the  computer  makes  a  capture. 
It  is  rather  cumbersome  to  transmit  this 
stop  flag  on  the  stack.  A  variable  is 
needed  to  do  the  job. 

UNMARKS  initializes  the  move  anal¬ 
ysis  routines:  WEFFECT,  which  analyze; 
bits  in  the  MAP  array  and  storing  the 
color  of  the  stones  to  be  processed,  given 
on  the  stack,  into  COLOR.  EXAMINE 
takes  a  board  location  and  calls  COUNTS 
to  count  the  liberties  of  the  group  of 
stones  connected  to  this  location;  EX¬ 
AMINE  then  returns  the  liberty  count  on 
the  stack. 

WCHO  and  BCHO  are  two  com¬ 
mands  that  scan  the  board  for  empty  but 
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Figure  2. 

Coding  scheme  developed  by  Dr.  Jonathan 
K.  Millen.  This  diagram  depicts  the  seven 
patterns  and  position  codes  in  which  a  desig¬ 
nated  black  move  will  usually  improve  the 
overall  black  configuration. 
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marked  locations  and  push  these  loca¬ 
tions  on  the  stack.  These  locations  are 
candidates  for  the  next  black  move,  and 
are  to  be  analyzed  using  the  lookahead 
technique.  A  zero  is  pushed  on  the  stack 
first  as  a  floor  for  the  location  values. 
These  locations  will  be  picked  up  by  CHO 
to  do  the  actual  analysis.  CHO  scans  the 
locations  on  the  stack  and  analyzes  their 
priorities.  When  it  finds  a  zero  on  the 
stack,  it  terminates  the  analysis.  The 
choice  of  the  best  move  is  stored  in 
BEST-MOVE.  WCHO  differs  from  BCHO 
in  that  it  does  not  scan  the  edges  of  the 
board,  because  it  is  futile  for  black  to 
play  on  the  board  edges  to  avoid  cap¬ 
turing. 

?CHO  is  used  to  determine  whether 
the  liberty  count  of  the  current  stone 
group  is  greater  than  the  value  stored  in 
BEST-LIBERTIES.  If  the  liberty  count  is 
greater,  there  is  no  need  to  do  the  move 
analysis  because  this  move  is  of  a  lower 
priority. 

WEFFECT  scans  all  the  black  stone 
groups.  If  a  black  group  has  a  liberty 
count  of  zero,  it  is  completely  surrounded 
by  white  stones  and  must  be  removed 
from  the  board.  If  the  liberty  count  is 
less  than  3  and  equal  or  less  than  BEST- 
LIBERTIES,  an  analysis  is  performed. 
If  a  more  pressing  move  is  found,  the  con¬ 
tents  of  BEST-MOVE,  BEST-COUNT, 
and  BEST-LIBERTIES  are  updated. 

BEFFECT  scans  all  the  white  stone 
groups.  If  a  white  group  has  a  liberty 
count  of  1 ,  the  computer  will  capture  this 
group  by  playing  into  the  last  liberty.  The 
STOP  flag  will  be  cleared  at  this  point. 
Otherwise,  BEFFECT  will  pick  the  best 
attacking  move. 


Terminal  Input 

?MOVE  in  screen  167  is  the  com¬ 
mand  that  accepts  a  number  from  the 
keyboard  as  the  next  move  by  the  human 
player.  It  prints  a  prompting  message, 
clears  the  rest  of  the  line,  and  waits  for  an 
input  string  from  the  keyboard,  ter¬ 
minated  by  a  carriage  return.  It  checks  the 
range  of  the  number  and  also  whether 
the  board  location  is  occupied.  It  will 
loop  until  a  valid  number  is  entered. 
Since  it  uses  the  standard  NUMBER 
command  to  do  the  number  conversion, 
it  will  abort  to  the  interpreter  if  an  in¬ 
valid  number  is  entered.  This  turns  out  to 
be  a  convenient  way  of  stopping  the  Go 
game  for  whatever  purpose.  The  aborted 
game  can  be  resumed  at  the  point  of 
interruption  by  the  command  RESUME. 

EOL  is  the  command  to  clear  the  rest 
of  the  current  line.  It  calls  an  Apple 
monitor  routine  to  do  the  job.  It  is  not 
absolutely  necessary  if  the  player  is  aware 
of  the  way  the  screen  display  is  managed. 

It  is  important  to  use  numbers  in  the 
base  19  format.  This  way  a  location  is 


selected  by  a  two-digit  number  from  00 
to  JJ,  without  spaces  between  the  two 
digits.  The  columns  and  the  rows  of  the 
board  are  numbered  accordingly  to  facili¬ 
tate  the  input  process. 


The  Main  Game  Loop 

The  command  for  playing  the  Go 
game  is  RESUME,  which  is  an  infinite 
loop.  In  this  loop,  first  the  current  board 
and  stones  are  printed  out  on  the  CRT 
screen,  the  player  is  asked  to  input  his 
move,  and  the  computer  then  goes  through 
the  WEFFECT,  BEFFECT,  and  PATS  rou¬ 
tines  to  decide  its  best  move.  The  com¬ 
puter  does  not  know  when  to  stop.  It  is 
the  human  player  who  usually  gets  worn 
out  and  quits. 

.BEST  is  used  to  print  out  the  var¬ 
iables  stored  in  BEST- MOVE,  BEST- 
COUNT,  and  BEST- LIBERTIES.  Printing 
out  this  information  is  interesting,  as  it 
shows  how  the  computer  arrives  at  its 
final  moves.  Since  the  computer  takes 
about  eight  seconds  to  decide  its  move, 
printing  the  intermediate  results  assures 
the  player  that  the  computer  is  not  idling. 

MAIN  is  the  initial  entry  point  of  the 
game.  It  clears  the  board,  places  the  nine 
handicap  stones  on  board,  sets  the  base  to 
19,  and  drops  into  the  RESUME  loop  to 
play  the  game.  If  the  game  is  interrupted 
by  intentionally  or  unintentionally  enter¬ 
ing  an  invalid  number,  a  new  game  can  be 
started  by  MAIN  or  the  current  game  can 
be  continued  by  RESUME. 


Concluding  Remarks 

The  resulting  program,  compiled  into 
Forth  code,  occupies  about  3  Kbytes  of 
memory.  The  response  time  for  each 
move  is  about  eight  seconds.  These  statis¬ 
tics  cannot  match  those  of  Dr.  Millen’s 
implementation  on  KIM-1  at  1  Kbyte  and 
one  second  response  time.  Inefficiency  in 
the  high-level  codes  and  poor  understand¬ 
ings  of  the  original  algorithm  are  among 
the  most  obvious  reasons  for  the  decrease 
in  performance.  I  don’t  think  much  can 
be  done  in  the  area  of  high-level  language, 
since  Forth  is  just  about  the  best  high- 
level  language  for  this  type  of  application. 
To  really  make  it  run  faster,  many  of  the 
routines  will  have  to  be  coded  in  assem¬ 
bly.  I  wonder  if  anybody  will  do  it,  ex¬ 
cept  Dr.  Millen. 

There  are  many  possible  ways  of  im¬ 
proving  the  performance  of  this  Forth 
program.  Restricting  the  scope  of  search¬ 
ing  and  analysis  will  greatly  speed  up  the 
execution.  I  tried  to  limit  the  searching 
to  two  5-by-5  areas  around  the  black 
stone  last  played  and  the  white  stone 
just  played.  This  shortcut  speeds  up  the 
response  time  to  less  than  two  seconds. 


without  significantly  weakening  the  per¬ 
formance  of  the  computer  part  of  the 
game.  Recording  the  results  of  a  whole 
pass  of  analysis  and  using  them  for  the 
next  pass  will  reduce  much  of  the  redun 
dant  work  performed  in  each  pass.  The 
results  of  analysis  need  only  minor  up¬ 
dating  and  the  best  move  can  be  quickly 
selected  in  the  next  pass. 

There  are  also  some  more  fundamen¬ 
tal  problems  not  properly  addressed  in 
the  original  program,  like  ko  fights,  the 
ladder  configuration,  Joseki’s,  etc.  These 
problems  can  be  solved  by  adding  more 
complicated  analysis  routines  to  the 
framework.  The  most  serious  problem  is 
probably  that  of  recognizing  two  eyes  in 
a  connected  group  of  stones  and  of 
generating  two  eyes  to  build  a  secured 
group,  immune  from  being  captured.  The 
counting  algorithm  is  not  capable  of 
doing  this  job.  To  accommodate  this  ca¬ 
pability,  a  radically  different  algorithm  is 
needed  to  do  much  more  sophisticated 
pattern  analysis.  A  full-scale  connectivity 
analysis  could  be  the  best  solution.  This 
route  is  currently  being  explored. 

There  will  be  no  end  to  the  look¬ 
ahead  analysis.  Professional  players  look 
ahead  ten  or  more  steps,  which  is  very 
difficult  to  simulate  by  computer.  Prob¬ 
ably  a  two-  or  three-step  lookahead  in 
combination  with  a  more  extensive  pat¬ 
tern  analysis  process  will  be  sufficient.  An 
important  area  is  the  opening  games  or 
Joseki’s.  Large  collections  of  Joseki’s 
compiled  into  data  bases  can  be  useful  in 
guiding  the  initial  games  in  the  four  cor¬ 
ners  on  the  board.  Not  much  intelligence 
is  needed  besides  searching  the  data  base 
for  the  particular  opening.  The  same  is 
true  for  the  game  endings.  However,  it 
will  then  be  necessary  that  the  computer 
have  disk  storage  to  hold  the  data  bases. 

Computerizing  the  game  of  Go  is 
very  interesting  and  challenging.  I  heartily 
congratulate  Dr.  Millen  for  opening  up 
this  field  with  his  excellent  work,  and 
hope  that  many  people  will  also  contrib¬ 
ute  their  expertise  to  a  fuller  implementa¬ 
tion  of  this  game  on  the  microcomputer. 
Hopefully,  we  will  have  the  computer 
Go  game  reach  the  level  of  sophistication 
of  the  chess  games  now  available  com¬ 
mercially. 


(  Listing  begins  on  page  63 ) 
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GO  -  Listing  (Text  begins  on  page  54) 


160  LIST 


O  (  STONES,  CHT, 10-1-82) 

1  VARIABLE  COLOR  VARIABLE  LIBERTY  1  CONSTANT  BLACK 

2  2  CONSTANT  WHITE  VARIABLE  MAP  360  ALLOT 

3  :  ?OUT  DUP  0<  OVER  360  >  OR  ;  19  CONSTANT  19 

4  :  7ST ONE  (  N - CODE  )  MAP  +  C@  ; 

5  :  NORTH  (  N1  -  N2  )  19  -  ;  :  SOUTH  19  +  5 

6  :  EAST  DUP  19  MOD  IS  =  IF  DROP  1000  ELSE  1+  THEN  ; 

7  :  WEST  DUP  19  MOD  IF  1-  ELSE  DROP  1000  THEN  ; 

8  (  COUNTS,  10-1-82  ) 

9  :  MARK  MAP  +  DUP  C@  128  OR  SWAP  C!  ; 

10  :  RECUR  LATEST  PFA  CFA  ,  ;  IMMEDIATE 

11  :  COUNTS  ?OUT  IF  DROP  EXIT  THEN  DUP  ?STONE  COLOR  @  =  IF 

12  DUP  MARK  DUP  NORTH  RECUR  DUP  EAST  RECUR 

13  DUP  SOUTH  RECUR  WEST  RECUR 

14  ELSE  DUP  ?STONE  0=  IF  MARK  1  LIBERTY  +! 

15  ELSE  DROP  THEN  THEN  ; 


161  LIST 


O  ( 

1  CC 

3  : 

4  s 

5 

6 

7 

8 
9 

10 
1 1 
12 


WT  .  "  O' 
XSAVE  LDX , 


DISPLAY,  CHT,  10-1-82  )  HEX  :  BK  .  "  ! 

)DE  HOME  XSAVE  STX,  24  STY,  25  STY,  FC22  JSR, 

NEXT  JMP,  END-CODE  DECIMAL 

LIMITS  361  0  ?  :  CROSS  - "  *, 

IND  2  SPACES  19  0  DO  I  2  .R  LOOP  5 
BOARD  HOME  IND  LIMITS  DO 

I  19  /MOD  SWAP  0=  IF  2  .R  ELSE  DROP  THEN 

I  7ST0NE  3  AND  DUP  0=  IF  CROSS  DROP 

ELSE  BLACK  =  IF  BK  ELSE  WT  THEN  THEN  LOOP 

PLACE  (  CODE  N  -  )  MAP  +  C!  ; 

GOBASE  19  BASE  !  ;  GOBASE 

HANDICAP  33  39  3F  93  99  9F  F3  F9  FF  9  0  DO 
BLACK  SWAP  PLACE  LOOP  ? 


DECIMAL 


13  :  CLRMAP  MAP  362  ERASE  ? 

14  :  KSTONE  (  N  )  MAP  +  O  SWAP  C!  ; 

15  :  PUT  SWAP  DO  COLOR  @  MAP  I  +  C!  LOOP  ; 


0  (  REMOVE,  CHT,  10-22-81) 

1  :  KMARK  MAP  +  DUP  C@  64  OR  SWAP  C!  ; 

2  :  REMOVE  (  N  -  ) 

3  ?OUT  IF  DROP  EXIT  THEN 

4  DUP  7ST ONE  67  AND  COLOR  @  =  IF 

5  DUP  KMARK  DUP  NORTH  RECUR  DUP  EAST  RECUR 

6  DUP  SOUTH  RECUR  DUP  WEST  RECUR  KSTONE  ELSE  DROP  THEN  ; 

7 

3  (  DESIGNATE,  UNMARK,  CHT,  10-1-82) 

9 

10  :  UNMARK  (  PATTERN  -  )  MAP  361  OVER  +  SWAP  DO 

11  I  C®  OVER  =  IF  I  Ce  3  AND  I  C!  THEN  LOOP  DROP  ? 

12  :  DESIGNATE  LIMITS  DO  I  7ST0NE  123  = 

13  IF  BLACK  I  PLACE  LEAVE  THEN  LOOP  ; 

14 

15 


163  LIST 

O  (  LOOKAHEAD,  CHT,  10-1-82) 

1  VARIABLE  BEST-MOVE  VARIABLE  BEST-LIBERTIES 

2  VARIABLE  BEST-COUNT  VARIABLE  ! COLOR 

3  :  LOOKAHEAD  (  MOVE  -  LIBERTY  ) 

4  BLACK  OVER  PLACE  COLOR  &  ! COLOR  !  BLACK  COLOR  ! 

5  O  LIBERTY  !  123  IJNMARK  129  UNMARK 

6  DUP  COUNTS  KSTONE  'COLOR  @  COLOR  f  LIBERTY  @  ; 

7 

8  (  EVAL,  CHT, 10-1-82) 

9 

10  :  EVAL  (  MOVE  LIBERTY  -  ) 

1 1  OVER  LOOKAHEAD  >R  I  BEST-COUNT  @  1  MAX  > 

12  OVER  BEST-LIBERTIES  &  >  0=  AND 

13  IF  BEST-LIBERTIES  !  BEST-MOVE  !  R>  BEST-COUNT  ! 

14  ELSE  2DR0P  R>  DROP  THEN  ; 

15 


(Continued  on  page  65 ) 


Dr.  Dobb’s  Journal,  Number  83,  September  1983 


GO  -  Listing 

(Listing  continued,  text  begins  on  page  54) 


164  LIST 

0  (  PATS,  MATCH,  CHT ,  10-1-82)  HEX 

1  VARIABLE  PATTERN  14  ,  44  ,  1400  ,  4400  ,  1001  ,  0110  ,  404  , 

2  401  ,  101  ,  104  ,  1010  ,  1010  PATTERN  !  DECIMAL 

3  :  ?RANGE  (  N  -  CODE  )  ?OUT  IF 

4  DROP  BLACK  ELSE  7ST0NE  3  AND  THEN  ; 

5  s  ?N  NORTH  7RANGE  5  :  ?E  EAST  7RANGE  ? 

6  :  ?S  SOUTH  7RANGE  ;  :  ?W  WEST  7RANGE  ? 

7  s  2*  DUP  +  ;  :  +4*  080  DO  DUP  ♦  DUP  +  +  LOOP  ; 

8  :  PNORTH  (  MOVE  -  PATTERN  )  DUP  ?N  IF  DROP  O  EXIT  THEN 

9  >R  I  NORTH  ?E  I  ?E  I  NORTH  EAST  DUP  ?E 

10  SWAP  ?N  I  NORTH  ?W  I 

1 1  ?W  R>  NORTH  WEST  DUP  ?W  SWAP  ?N  +4*  ? 

12  :  PE AST  DUP  ?E  IF  DROP  0  EXIT  THEN 

13  >R  I  EAST  ?S  I  ?S  I  EAST  SOUTH  ?S 

14  I  EAST  SOUTH  ?E  I  EAST  ?N  I  ?N 

15  I  EAST  NORTH  ?N  R>  EAST  NORTH  ?E  +4*  ; 


165  LIST 

0  (  PATS,  MATCH,  CHT,  10-1-82)  :  FIX  DUP  ROT  AND  ; 

1  :  PSOUTH  (  MOVE  PATTERN  )  DUP  ?S  IF  DROP  0  EXIT  THEN 

2  :  R  I  SOUTH  ?E  I  ?E  I  SOUTH  EAST  ?E  I  SOUTH  EAST  0 

3  I  SOUTH  ?W  I  ?W  I  SOUTH  WEST  ?W  R>  SOUTH  WEST  ?S  +4*  5 

4  s  PWEST  DUP  ?W  IF  DROP  O  EXIT  THEN 

5  >R  I  WEST  ?S  I  ?S  I  WEST  SOUTH  ?S  I  WEST  SOUTH  ?W 

6  I  WEST  ?N  I  ?N  I  WEST  NORTH  ?N  R>  WEST  NORTH  ?W  +4*  ; 

7  :  MATCH  <  PATTERN -  F)  DUP  IF  0  12  0  DO  OVER  PATTERN  I  2* 

8  +  @  FIX  =  IF  1+  LEAVE  THEN  LOOP  SWAP  DROP  THEN  5 

9  :  EVPAT  1  BEST-COUNT  !  2  EVAL  ! 

10  :  PATS  LIMITS  DO  I  7ST0NE  WHITE  AND  IF  I  PNORTH  MATCH 

11  IF  I  NORTH  EVPAT  LEAVE  ELSE  I  PEAST  MATCH 

12  IF  I  EAST  EVPAT  LEAVE  ELSE  I  PSOUTH  MATCH 

13  IF  I  SOUTH  EVPAT  LEAVE  ELSE  I  PWEST  MATCH 

14  IF  I  WEST  EVPAT  LEAVE  THEN  THEN  THEN  THEN  THEN  LOOP  5 

15 


166  LIST 

O  (  WEFFECT,  BEFFECT,  CHT,  10-1-82) 

1  VARIABLE  7ST0P  :  STOP  0  7ST0P  !  5 

2  :  UNMARKS  (  COLOR - )  129  UNMARK  130  UNMARK  COLOR  !  5 

3  :  EXAMINE  128  UNMARK  0  LIBERTY  !  COUNTS  LIBERTY  @  ; 

4  :  WCHO  0  341  19  DO  I  19  MOD  7DUP  IF  18  -  IF  I  7ST0NE  128  *= 

5  IF  I  THEN  THEN  THEN  LOOP  ? 

6  :  CHO  BEGIN  7DUP  WHILE  LIBERTY  £  EVAL  REPEAT  5 

7  :  7CH0  BEST-LIBERTIES  @  LIBERTY  @  <  0=  ; 

8  :  BCHO  0  LIMITS  DO  I  7ST0NE  128  =  IF  I  THEN  LOOP  ? 

9  :  WEFFECT  BLACK  UNMARKS  360  BEST-LIBERTIES  • 

10  LIMITS  DO  I  7ST0NE  BLACK  =  IF  I  EXAMINE 

11  0=  IF  I  REMOVE  ELSE  LIBERTY  @  3  < 

12  IF  7CH0  IF  WCHO  CHO  THEN  THEN  THEN  THEN  LOOP  ; 

13  s  BEFFECT  WHITE  UNMARKS  LIMITS  DO  I  7ST0NE  WHITE  =  IF 

14  I  EXAMINE  1  =  IF  DESIGNATE  I  REMOVE  LEAVE  STOP 

15  ELSE  7CH0  IF  BCHO  CHO  THEN  THEN  THEN  LOOP  ? 


167  LIST 

O  <  7M0VE,  CHT,  10-1-82)  HEX 

1  CODE  EOL  XSAVE  STX,  FC9C  JSR,  XSAVE  LDX ,  NEXT  JMP,  END-CODE 

2  DECIMAL 

3  :  7M0VE  BEGIN  CR  . "  YOUR  MOVE:  "  EOL 

4  0  >IN  !  TIB  @  19  EXPECT  32  WORD  NUMBER  DROP  DUP  .  70UT 

5  IF  .  "  RANGE?  "  DROP  O  ELSE  DUP  7ST0NE  3  AND  0= 

6  IF  WHITE  SWAP  PLACE  1  ELSE  . "  OCCUPIED."  DROP  O  THEN 

7  THEN  UNTIL  ; 

3  (  RESUME,  MAIN,  CHT,  10-1-82  ) 

9  :  .BEST  3  SPACES  BEST-MOVE  ?  BEST-COUNT  7  BEST-LIBERTIES  7  ? 

10  :  RESUME  BEGIN  BOARD  7M0VE  1  7ST0P  !  0  BEST-COUNT  • 

11  WEFFECT  .BEST  BEFFECT  .BEST  7ST0P  &  IF  PATS 

12  BLACK  BEST-MOVE  @  .BEST  PLACE  THEN  AGAIN  ! 

13  :  MAIN  GOBASE  CLRMAP  HANDICAP  RESUME  5 

14  EXIT 

15 


End  Listing 
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SEND  and  RCV: 

A  Forth  Implementation  of  the  XMODEM  Protocol 


In  the  dark  ages  after  the  IBM  PC  was 
delivered  but  before  everyone  jumped 
on  the  bandwagon  to  provide  software 
for  it,  I  needed  to  transfer  files  to  and 
from  CP/M  systems.  I  knew  that  Ward 
Christensen’s  XMODEM  program  was  the 
de  facto  standard  for  file  transfer  between 
CP/M  systems,  so  all  I  had  to  do  was 
write  a  program  for  the  IBM  PC  that  used 
the  same  protocol.  Because  I  had  just 
received  a  copy  of  PC/FORTH  from 
Laboratory  Microsystems  and  I  wanted 
to  learn  Forth  programming,  I  did  the 
natural  thing:  I  wrote  SEND  and  RCV, 
Forth  words  that  do  XMODEM  file 
transfers. 

Before  we  get  into  the  Forth  words, 
perhaps  a  short  introduction  to  the 
XMODEM  protocol  is  in  order.  Dr.  Dobb’s 
Journal  has  published  many  articles  over 
the  years  about  various  implementations 
of  this  protocol,  so  many  of  you  are  al¬ 
ready  familiar  with  it.  For  those  of  you 
who  aren’t,  the  protocol  provides  a 
method  of  transferring  files  and  making 
sure  that  each  piece  of  the  file  is  trans¬ 
ferred  without  error. 

The  XMODEM  Protocol 

Before  anything  is  transferred,  the 
sender  and  the  receiver  must  get  in  synch 
with  one  another.  To  do  this,  the  sender 
waits  for  the  ASCII  character  NAK  (Neg¬ 
ative  AcKnowledge,  or  decimal  21)  to  be 
sent  by  the  receiver.  When  the  sender  gets 
the  first  NAK,  it  starts  transferring  the 
file  one  piece  at  a  time. 

The  file  is  transferred  in  128 -byte 
chunks  called  “sectors.”  The  sender  pre¬ 
cedes  each  sector  with  a  3-byte  sequence 
called  a  “sector  header.”  The  sector 
header  consists  of  the  ASCII  character 
SOH  (Start  Of  Header,  or  decimal  1), 
followed  by  the  sector  number  as  an 
ASCII  character  (0-255),  followed  by  the 
logical  complement  of  the  sector  number 
(255-0).  After  the  sector  header  is  sent, 
first  the  sector  and  then  a  single  byte 
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called  the  “checksum”  are  sent.  The 
checksum  is  the  sum  of  every  byte  in  the 
sector,  modulo  256,  so  it  will  be  a  num¬ 
ber  from  0  to  255.  When  the  sector 
header,  the  sector,  and  the  checksum  are 
sent,  the  sender  waits  for  a  response  from 
the  receiver. 

The  receiver  receives  the  3 -byte  sec¬ 
tor  header,  the  128 -byte  sector,  and  the 
1-byte  checksum.  It  makes  sure  that  the 
sector  header  is  correctly  formed.  It  saves 
the  128 -byte  sector  into  a  file  buffer  and 
computes  a  checksum  by  adding  all  the 
bytes  together,  modulo  256.  Then  it 
compares  its  computed  checksum  with 
the  checksum  byte  it  received  from  the 
sender.  If  any  characters  have  been  re¬ 
ceived  differently  than  they  were  sent, 
the  two  checksums  will  not  have  the  same 
value,  and  the  receiver  knows  that  the 
sector  is  in  error.  If  the  receiver  decides 
that  no  errors  have  occurred,  it  sends  the 
ASCII  character  ACK  (ACKnowledge,  or 
decimal  6)  to  the  sender.  If  the  receiver 
finds  an  error,  it  responds  with  the  ASCII 
character  NAK. 

The  sender,  having  sent  a  sector, 
awaits  the  receiver’s  response.  If  the  re¬ 
ceiver  responds  with  a  NAK,  an  error  has 
occurred,  and  the  sender  retransmits  the 
same  sector.  If  the  receiver  responds  with 
an  ACK,  the  sector  arrived  safely,  so  the 
sender  sends  the  next  sector  in  the  file. 
When  the  sender  runs  out  of  sectors  to 
send,  it  transmits  the  ASCII  character 
EOT  (End  Of  Transmission,  or  decimal  4) 
and  waits  for  the  receiver  to  transmit  an 
ACK,  signaling  all’s  right  at  the  receiving 
end. 

If  the  line  between  the  sender  and 
the  receiver  is  so  noisy  that  nothing  can 
be  transmitted  without  errors,  the  sender 
will  eventually  give  up.  Also,  if  the 
sender  receives  the  ASCII  character  CAN 
(CAN cel,  or  decimal  24)  when  it  is  wait¬ 
ing  for  an  ACK  or  a  NAK,  it  will  stop 
trying  to  send. 

Using  SEND  and  RCV 

To  use  SEND  or  RCV,  first  load  them 
into  Forth.  Since  PARSE  is  a  CODE  word, 
the  assembler  must  be  already  loaded. 
Once  they  are  loaded  into  Forth,  type 

SEND  filename. ext 

to  start  the  transmission  of  the  PCDOS 
file  specified.  Similarly,  type 

RCV  filename.ext 

to  start  receiving  the  PCDOS  file  specified. 
As  each  sector  is  sent  or  received,  its 
number  is  displayed  on  the  screen  so  you 


can  follow  its  progress.  You  can  manually 
terminate  the  transfer  at  any  point  by 
hitting  Ctrl-X  at  the  keyboard.  When  the 
whole  file  is  sent,  RCV  will  display 

EOT  received 
while  SEND  displays 

EOT  sent  -  ack’d 

indicating  that  the  sender  has  sent  the 
required  End  of  Transmission  character 
and  the  receiver  has  received  and  ac¬ 
knowledged  it. 

Since  these  routines  may  be  operat¬ 
ing  at  high  baud  rates  (up  to  9600  baud), 
the  receiver  can’t  take  the  time  to  print 
long  error  messages.  Thus,  “H— ”  indicates 
a  header  error,  “S— ”  a  sector  error, 
“C— ”  a  checksum  error,  and  “T— ”  a 
timeout  error.  (A  timeout  error  is  when 
no  data  have  arrived  within  a  certain 
period  of  time.)  After  an  error  occurs, 
“NAK  sent”  indicates  that  the  receiver 
has  sent  a  NAK  to  the  sender.  The  NAK 
tells  the  sender  to  retransmit  the  sector. 


Implementation  of  SEND  and  RCV 

SEND  and  RCV  are  simply  the  Forth 
words  that  implement  the  actions  of  the 
sender  and  receiver.  SEND  first  calls 
SEND-SETUP  to  find  the  file  that  will 
be  transferred,  to  open  it,  and  to  report 
the  file’s  size.  WAIT-ACK  waits  for  the 
receiver  to  send  a  NAK  (or  an  ACK)  to 
start  the  transfer.  If  WAIT-ACK  receives 
a  CAN,  it  closes  the  opened  file  and 
stops.  Otherwise,  SEND  enters  a  loop 
that: 

(1)  Checks  the  keyboard  for  a  Ctrl-X, 
which  would  cancel  the  transfer. 

(2)  Calls  READ-SECT  to  get  another 
sector  from  the  file.  If  READ- SECT 
gets  an  end-of-file  error,  END-SEND 
is  invoked  to  end  the  transfer  nor¬ 
mally. 

(3)  Calls  SEND-HDR,  SEND-SECT,  and 
SEND-CKSUM  to  send  the  sector 
header,  the  sector,  and  the  check¬ 
sum,  respectively. 

(4)  Waits  for  the  receiver  to  acknowledge 
the  transfer.  If  an  ACK  is  received, 
the  variable  SSEC  is  incremented,  so 
the  next  sector  will  be  sent.  If  a  NAK 
is  received,  SSEC  isn’t  incremented, 
so  the  same  sector  will  be  sent  again. 
In  either  case,  the  loop  starts  over 
from  the  beginning. 

RCV  works  in  a  similar  manner. 
RCV-SETUP  makes  sure  that  the  file  to 


66 


Dr.  Dobb’s  Journal,  Number  83,  September  1 983 

523 


be  received  is  properly  created.  If  the  file 
already  exists,  you  are  asked  if  you  want 
to  overwrite  it.  Then  RCV  sends  the  first 
NAK  to  get  the  ball  rolling.  Now  RCV 
goes  into  a  loop  that : 

(1)  Checks  the  keyboard  for  a  Ctrl-X, 
which  would  cancel  the  transfer. 

(2)  Waits  for  an  ASCII  SOH,  which  indi¬ 
cates  the  start  of  a  sector  header. 

(3)  Calls  RCV-HDR  to  receive  the  header 
and  check  it  for  validity. 

(4)  Calls  RCV-SECT  to  receive  the  sec¬ 
tor  and  compute  the  checksum. 

(5)  Calls  RCV-CKSUM  to  receive  the 
checksum  and  compare  it  to  the 
checksum  computed  by  RCV-SECT. 

(6)  Calls  SAVE-SECT  to  save  the  sector 
in  the  file  on  disk. 

(7)  Sends  an  ACK  to  the  sender,  and 
starts  the  loop  over. 

If  RCV  finds  an  error,  it  calls  RCVERR, 
which  waits  for  the  sender  to  stop  send¬ 
ing  and  sends  a  NAK.  The  sender  then 
retransmits  the  sector,  and  RCV  restarts 
the  loop. 


Conclusion 

SEND  and  RCV  provide  a  mechanism 
for  the  Forth  programmer  to  transfer  files 
to  and  from  CP/M  systems  that  have 
XMODEM  and  to  and  from  other  PCDOS 
systems  that  have  a  program  that  imple¬ 
ments  the  XMODEM  protocol.  They  were 
written  for  Laboratory  Microsystem’s  PC/ 
FORTH,  which  runs  under  PCDOS,  but 
they  are  easily  adaptable  to  other  Forths 
running  on  other  machines. 

Since  SEND  and  RCV  are  intended 
to  transfer  files,  some  file  handler  words 
must  be  added  to  most  Forth  implemen¬ 
tations.  One  possible  set  of  file  handler 
words  is  presented  in  screens  2-6.  These 
words  are  included  in  PC/ FORTH,  al¬ 
though  I’ve  made  a  few  modifications  and 
additions.  To  adapt  SEND  and  RCV  to 
other  systems,  you  must  redefine  these 
words  to  work  in  your  particular  environ¬ 
ment.  Also,  the  words  on  screen  7  are 
specific  to  the  IBM  PC;  they  control  the 
serial  port,  so  you  will  also  need  to  revise 
them  for  other  machines. 

The  glossary  that  follows  is  a  word- 
by-word  description  of  the  routines  pre¬ 
sented  in  Listing  One  (page  74).  The 
words  appear  in  the  same  order  as  they 
do  in  the  listing.  The  glossary  is  intended 
to  help  you  understand  what’s  been  im¬ 
plemented,  so  you  can  modify  the  rou¬ 
tines  to  best  suit  your  needs. 

Glossary  For  SEND/RCV  Listing 

Screen  1:  These  are  various  words 
that  extend  PC  /FORTH. 


0<>  n-f 

If  n<>0,  then  f=l,  else  f=0. 

<>  nl  n2  -  f 

If  nl=n2,  then  f=l,  else  f=0. 

>=  nl  n2  -  f 

If  nl>  =n2,  then  f  =  1 ,  else  f=0. 

<=  nl  n2  —  f 

If  nl<=n2,  then  f=l,  else  f=0. 

NOT  nl  -  n2 

n2  is  the  logical  complement  of  nl. 

RESTART 

Compiler  word.  Usage:  RESTART 
Used  inside  BEGIN  . . .  AGAIN  or  BEGIN 
. . .  UNTIL  loops  to  start  them  over  from 
the  beginning. 


Screens  2-6:  This  is  a  PCDOS  file 
handler,  defined  in  terms  of  a  PC/FORTH 
primitive  word  FDOS  that  provides  low- 
level  access  to  the  PCDOS  operating  sys¬ 
tem  cajls.  Although  these  screens  are 
operating  system  dependent,  they  are  not 
machine  dependent.  Thus,  they  will  work 
with  PCDOS  on  machines  other  than  an 
IBM  PC. 

FCB 

Defining  word.  Usage:  FCB  name 
Constructs  a  PCDOS  file  control  block. 
After  “name”  is  defined  to  be  an  FCB,  it 
will  push  the  FCB’s  address  on  the  stack. 

SET- DMA  fcb-addr  — 

Sets  the  buffer  area  for  file  transfers  in¬ 
volving  the  specified  FCB. 

7BUFFER-ADDR  fcb-addr  -  fcb-offset 
Pushes  the  location  of  the  specified  FCB’s 
buffer  area. 

OPEN-FILE  fcb-addr  —  status 

Status=0  if  the  file  indicated  by  the  FCB 
was  successfully  opened;  any  error,  and 
status=255. 

CLOSE-FILE  fcb-addr  —  status 

Same  as  OPEN-FILE,  only  closing  the 
file. 

MAKE-FILE  fcb-addr  —  status 

Same  as  OPEN-FILE,  only  creating  a  new 
file. 

DELETE-FILE 

Not  used  by  SEND  or  RCV. 

SEARCH -FILE 

Not  used  by  SEND  or  RCV. 

NEXT -FILE 

Not  used  by  SEND  or  RCV. 

RENAME-FILE 

Not  used  by  SEND  or  RCV. 


READ-SEQ  fcb-addr  —  status 
Reads  the  next  block  from  the  file  indi¬ 
cated  by  the  FCB;  status=0  if  the  opera¬ 
tion  is  a  success.  (Note  that  this  is  differ¬ 
ent  than  OPEN-FILE,  where  a  status  of  0 
indicated  an  error.) 

WRITE-SEQ  fcb-addr  —  status 

Writes  the  block  from  the  buffer  to  the 
file  indicated  by  the  FCB;  status=0  if  the 
operation  is  a  success. 

READ -RANDOM 

Not  used  by  SEND  or  RCV. 

WRITE -RANDOM 

Not  used  by  SEND  or  RCV. 

PARSE  fcb-addr  buf-ptr  —  fl 

Looks  at  the  file  specification  stored  in  the 
buffer  pointed  to  by  buf-ptr  and  moves  it 
into  the  FCB,  properly  formatted.  The 
return  code  is  f  1 = 0  if  the  file  spec  is  OK, 
f  1= 1  if  the  file  spec  contains  wildcards, 
and  f  1=255  if  the  file  spec  is  not  valid. 

FILENAME  fcb-addr  -  fl 

Usage:  fcb  FILENAME  name 
Parses  a  file  specification  from  the  input 
stream  into  the  FCB  at  fcb-addr.  fl  is 
returned  the  same  way  as  in  PARSE: 
f  1=0  is  an  OK  spec,  f  1= 1  is  a  wildcard 
spec,  fl=  255  is  an  invalid  spec. 

IN-NAME  fcb-addr -fl 

Prompts  for  a  file  specification,  which 
gets  put  into  the  FCB  at  fcb-addr.  fl  is 
returned  as  in  PARSE. 

OUT-NAME  fcb-addr  - 

Displays  the  file  name  that  is  contained  in 
the  FCB  at  fcb-addr. 

Screen  7:  This  is  the  only  machine 
dependent  screen  in  the  entire  listing. 
These  words  provide  low-level  serial  port 
support:  send  a  byte,  receive  a  byte, 
check  to  see  if  a  byte  has  arrived,  etc. 

?COM  -  f 

If  f=l ,  a  byte  is  waiting  at  the  serial  port 

to  be  read. 

WAITOUT 

Loops  until  the  serial  port  can  accept  a 
byte  to  be  transmitted. 

WAITIN 

Loops  until  a  byte  is  waiting  at  the  serial 
port  to  be  read. 

XIN  -  n 

Reads  a  byte  from  the  serial  port. 

XOUT  n- 

Writes  a  byte  to  the  serial  port.  If  n=-l, 
nothing  is  written  to  the  port. 

CLEAR 

Waits  until  there  are  no  characters  waiting 
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to  be  read. 


1300 


Initializes  the  serial  port  to  300  baud,  8 
bits  are  transmitted,  no  parity,  1  stop  bit, 
and  turns  on  the  DTR  signal.  If  you  want 
to  change  the  baud  rate,  the  HEX  180 
should  be  changed  as  follows: 

To  Get:  Use  HEX: 


300  baud  180 

1200  baud  60 

4800  baud  18 

9600  baud  C 


Screen  8:  These  are  the  variables  and 
constants  used  by  SEND  and  RCV. 

LONG  TIMEOUT  - 


Gets  the  standard  XMODEM  sector 
header  and  checks  it  for  validity;  f=-l  if 
the  header  is  incorrect. 

RCV- SECT  -  f 

Gets  the  sector  and  computes  a  checksum; 
f=  -1  if  there  is  an  error. 

RCV-CKSUM  -  f 

Gets  the  checksum  sent  by  the  sender  and 
compares  it  with  the  computed  checksum; 
f=-l  if  they  don’t  match. 

SAVE-SECT 

Writes  the  sector  from  the  buffer  into  the 
file  on  disk. 

DISP-CHR  n  - 

Displays  unexpected  characters. 


Sets  the  timer’s  initial  value  to  30000,  so 
the  timer  will  wait  a  relatively  long  time 
before  generating  a  timeout  error. 

SHORT-TIMEOUT  - 

Sets  the  timer’s  initial  value  to  10000,  so 
the  timer  will  wait  a  relatively  short  time 
before  generating  a  timeout  error. 


RCV 

Usage:  RCV  filespec.ext 
Receives  the  file  specified  from  the  serial 
port  using  the  XMODEM  protocol  (see 
the  text  of  the  article). 

Screens  14-17:  These  are  the  SEND 
and  auxiliary  routines. 


Screens  9-13:  These  are  the  RCV 
and  auxiliary  routines. 

RCV-SETUP 

Creates  the  file  to  be  received.  If  the  file 
already  exists,  asks  if  it’s  OK  to  overwrite 
the  existing  file  with  the  incoming  file, 
then  sets  a  few  variables. 

TIMED -IN  -  n 

Waits  a  predetermined  time  for  a  byte  to 
be  received.  If  nothing  shows  up  during 
that  time,  then  n=-l,  and  we  say  a  time¬ 
out  has  occurred. 

GOBBLE 

Ignores  all  incoming  characters  until  no 
characters  arrive  for  a  certain  period  of 
time;  that  is,  GOBBLE  waits  until  a  time¬ 
out  is  generated. 

ABEND 

In  case  of  an  abnormal  end,  ABEND  in¬ 
forms  you  and  closes  the  file  that  is  being 
sent/received. 

RCVERR 

Invokes  GOBBLE  to  clear  the  line,  then 
sends  a  NAK  to  indicate  that  the  receiver 
has  detected  an  error.  If  more  than 
MAXERR  errors  have  occurred,  the 
transmission  is  aborted. 

7TERMABORT  -  f 

f=  -1  if  Ctrl-X  has  been  typed  on  the 
keyboard  (typing  Ctrl-X  is  a  manual 
cancel  of  the  transmission). 

NOREND 

Normal  end  that  closes  the  file  being  sent 
or  received. 

RCV-HDR  -  f 


WAIT-ACK 

Waits  for  an  ACK,  a  NAK,  a  CAN,  a  time¬ 
out,  or  a  manual  cancel  (CTRL-X). 

READ-SECT  -  f 

Reads  the  next  sector  to  be  transferred 
from  the  disk  file  into  the  buffer;  f=-l  if 
End  Of  File. 

SEND-HDR 

Transmits  a  sector  header. 

SEND -SECT 

Transmits  a  sector  and  computes  a  check¬ 
sum. 

SEND-CKSUM 

Transmits  the  checksum  computed  by 
SEND-SECT. 

END-SEND 

Transmits  an  EOT  and  waits  until  it  gets 
an  ACK  from  the  receiver,  then  closes  the 
file  being  sent. 

SEND-SETUP 

Initializes  the  serial  port,  inputs  the  file 
specification,  opens  the  file,  and  reports 
on  the  file’s  size. 

SEND 

Usage:  SEND  filespec.ext 
Transmits  the  file  specified  to  the  serial 
port  using  the  XMODEM  protocol  (see 
the  text  of  the  article). 

( Listing  begins  on  page  74 ) 
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SEND  and  RCV  -  Listing 

(Text  begins  on  page  66) 


Screen  #  O 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

Copyright  1982,  1983  by  Robert  Taylor  III 
All  rights  reserved. 

These  routines  are  not  to  be  used  for  cotiercial  purposes, 
but  unliiited  personal,  non-co**ercial  use  is  allowed. 

For  a  full  co**unication  package  that  includes  these  routines, 
please  order  "PC/TERM"  fro*: 

Laboratory  Hicrosyste*s 
4147  Beethoven  St. 

Los  Angeles,  CA  90066 

PC/TERM  is  an  extension  package,  designed  to  be  run  with 
Laboratory  Microsyste»s’  PC/FORTH.  It  is  best  used  with  a 
Hayes  Siartiode*. 


Screen  #  1 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

(  various  supple»entary  ari thaetic  functions  I 

:  0<>  0=  0=  ;  :  0  =  0-;  :  >=  <  0=  ;  :  <=  >  0=  ; 

:  NOT  -1  XOR  ; 

(  extension  to  FORTH  compiler:  used  inside  a  BEGIN  loop  to  ) 
(  start  the  loop  over  fro*  the  beginning,  use:  ) 

(  BE6IN  xx  IF  RESTART  END  IF  AGAIN  > 

:  RESTART  (  ;  use  in  BEGIN  loops  to  start  the*  over! 

7C0MP  7STACK  0  0  >R  >R 

BEGIN  DUP  1  <>  WHILE  >R  >R  REPEAT 

2DUP  [COMPILE!  AGAIN 

BEGIN  R>  R>  2DUP  0  0  D=  UNTIL  2DR0P  ;  IMMEDIATE 
--> 


Screen  #  2 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  1 

FORTH  DEFINITIONS  DECIMAL 
(  used  in  the  for*:  FCB  fcb-na*e  ) 

:  FCB  <BUILDS  HERE  165  ERASE  165  ALLOT 

DOES)  ; 

I  length  of  fcb,  displaceient  to  actual  i/o  buffer  ) 

37  CONSTANT  BUFFER-OFFSET 

(  fcb-addr  —  ) 

:  SET-DMA  26  SNAP  BUFFER-OFFSET  +  FDOS  2DR0P  ; 

(  fcb-addr  —  ) 

:  7BUFFER-ADDR  BUFFER-OFFSET  +  ; 

--> 


Screen  #  3 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

(  for  all  file  operations,  status  code  =  OFFh  if  ) 

(  operation  failed,  zero  if  operation  successful.  ) 

(  fcb-addr  —  status-code  ) 

:  OPEN-FILE  15  SNAP  FDOS  DROP  255  AND  ; 

:  CLOSE-FILE  16  SNAP  FDOS  DROP  255  AND  ; 

:  MAKE-FILE  22  SNAP  FDOS  DROP  255  AND  ; 

:  DELETE-FILE  19  SNAP  FDOS  DROP  255  AND  ; 

:  SEARCH-FILE  17  SNAP  FDOS  DROP  255  AND  ; 

:  NEXT-FILE  18  SNAP  FDOS  DROP  255  AND  ; 

:  RENAME-FILE  23  SNAP  FDOS  DROP  255  AND  ; 


Screen  #  4 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

(  for  all  record  operations,  status  code  =  buffer  address  ) 
t  if  operation  successful,  zero  if  operation  failed.  ) 

(  fcb-addr  —  status-code  For  REAB-SEB,  partial  =  success  ) 

:  READ-SEE  DUP  DUP  SET-DMA  20  SNAP  FDOS  DROP  255  AND  1  = 

IF  DROP  0  ELSE  BUFFER-OFFSET  +  THEN  ; 

:  NRITE-SEB  DUP  DUP  SET-DMA  21  SNAP  FDOS  DROP  255  AND  0= 

IF  BUFFER-OFFSET  +  ELSE  DROP  0  THEN  ; 

(  fcb-addr  record-nu»ber  —  status-code  ) 

:  READ-RANDOM  OVER  33  +  !  DUP  DUP  SET-DMA  33  SNAP  FDOS  DROP 
255  AND  0=  IF  BUFFER-OFFSET  +  ELSE  DROP  0  THEN  ; 

:  WRITE-RANDOM  OVER  33  +  !  DUP  DUP  SET-DMA  34  SNAP  FDOS  DROP 
255  AND  0=  IF  BUFFER-OFFSET  ♦  ELSE  DROP  0  THEN  ; 

--> 


Screen  #  5 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

BASE  S  HEX 

(  use  PARSE  to  analyze  a  typed-in  file  specification.  ) 

CODE  PARSE  (  fcb-addr  buf-ptr  —  fl;  0=0K,  1=NILD,  255=BAD  ) 

AX  POP  DX  POP  BP  PUSH  SI  PUSH  ES  PUSH 
DI,  DX  MOV  DX,  DS  MOV  ES,  DX  MOV  SI,  AX  MOV 
AX,  t  2901  MOV  t  21  INT  AX,  t  OOFF  AND 

ES  POP  SI  POP  BP  POP  AX  PUSH  NEXT 

BASE  ! 


74 

526 


Dr.  Dobb’s  Journal,  Number  83,  September  1983 


Screen  #  6 

!  SEND  and  RCV  files  using  XMODEM  protocol 


06/03/83  ) 


:  FILENAME  (  fcb-addr  —  fl;  fl:0=0X,l=wild,255  not  OK  ) 
BL  WORD  HERE  It  PARSE  j 

:  IN-NAME  (  fcb-addr  —  fl;  fl:0=0K, l=wild,255  not  DK  1 
Enter  file  specification:  ’ 

HERE  30  EXPECT  HERE  PARSE  ; 

:  OUT-NAME  (  fcb-addr  —  ) 

DUP  CS  -DUP  IF  64  t  EMIT  58  EMIT  (  :  )  ENDIF 
9  1  DO  DUP  I  t  CS  DUP  32  =  IF  DROP  LEAVE  ELSE  EMIT  ENDIF  LOOP 
46  EMIT  (  .  ) 

12  9  DO  DUP  I  t  [J  DUP  32  =  IF  DROP  LEAVE  ELSE  EMIT  ENDIF  LOOP 
DROP  : 


Screen  #  7 

1  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

HEX 

:  7C0M  3FD  PCS  1  AND  ;  (  char  available'’  I 

:  MAI  TOUT  BE6IN  3FD  PCS  20  AND  UNTIL  ;  (  wait  for  TX  eipty  I 

:  MAITIN  BE6IN  ?C0M  UNTIL  ;  (  wait  for  char  avail  ! 

:  XIN  3F8  PCS  ;  (  receive  a  char  ) 

:  TOUT  It  -DUP  IF  HAITOUT  1-  3FB  PC!  THEN  ;  (  TX  1  chr,  exc.-l) 

:  CLEAR  3COM  IF  XIN  DROP  ENDIF  ;  (  clear  line  garbage  ) 

:  1300  80  3FB  PC'  180  3F8  P!  3  3FB  PC!  1  3FC  PC'  ; 

DECIMAL 


Screen  #  8 

1  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

FCB  XFER  (  FCB  area  where  file  is  opened  ) 

0  VARIABLE  CXSUM  (  check  sui  byte  for  a  128  byte  sector  1 
1  error  variables  1 

0  VARIABLE  ERRS  10  CONSTANT  MAXERR  0  VARIABLE  NAK-CT 

(  various  sector  variables:  rev  sec,  send  sec,  expected  sec  ) 
0  VARIABLE  RSEC  0  VARIABLE  SSEC  0  VARIABLE  XSEC 

(  ascii  characters  with  special  leaning  in  the  XMODEM  protocol! 
0  CONSTANT  NUL  24  CONSTANT  CAN  1  CONSTANT  SOH 

4  CONSTANT  EOT  6  CONSTANT  ACK  21  CONSTANT  NAK 

(  tiler  control:  TIM-CT  is  the  tiler’s  initial  setting.  ) 

10000  CONSTANT  TIM-CT  0  VARIABLE  TIMER 
:  LONG-TIMEOUT  30000  ’  TIM-CT  !  ;  (  longer  tiieout  dur.  ) 

:  SHORT-TIMEOUT  10000  ’  TIM-CT  !  ;  (  shorter  tiieout  dur.)' 

--> 


Screen  #  9 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

:  RCV-SETUP 
1300 

XFER  FILENAME  DROP  CR  XFER  OPEN-FILE  0= 

IF  .'  File  exists.  OX  to  replace?  *  PCKEY  CR 
-DUP  0  <>  I  223  AND  89  <> 

IF  SUIT  ENDIF 
XFER  CLOSE-FILE  DROP 


ENDIF 

XFER  MAXE-FILE 

IF  .’  Can’t  create  file:  1  XFER  OUT-NAME  CR  QUIT 
ENDIF 

XFER  DUT-NAHE  .’  created  and  opened.'  CR 
0  XFER  32  +  C!  0  RSEC  !  0  XSEC  !  0  NAK-CT  ! 

--> 


Screen  #  lO 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ! 

:  TIMED-IN  TIM-CT  TIMER  ! 

BE6IN  ?C0M  IF  XIN  EXIT  ENDIF  -1  TIMER  +!  TIMER  S  0= 

UNTIL  -1  ; 

:  BOBBLE  BEGIN  TIMED-IN  -1  =  UNTIL  ; 

:  ABEND  .*  Aborting.”  CR  XFER  CLOSE-FILE 
IF  .'  Can’t  close  file:  '  XFER  OUT-NAME  CR  ENDIF  ; 

:  RCVERR  BOBBLE  1  NAK-CT  +!  NAX-CT  S  MAXERR  > 

IF  CAN  XOUT  .*  Exceeded  laxiiui  errors.'  CR 
ABEND  QUIT 

ENDIF 

.’  NAX  sent.'  CR  NAX  XOUT  ; 


Screen  #  11 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

:  7TERMAB0RT  0  7TERMINAL  IF  DROP  XEY  24  = 

IF  .'  Cancelled  at  console.'  CR  -1  ENDIF  ENDIF  ; 

:  NOREND  .'  EOT  Received.'  CR  ACX  XOUT  XFER  CLOSE-FILE 
IF  .'  Can’t  close  file:  '  XFER  OUT-NAME  CR  ENDIF  ; 

:  RCV-HDR  TIMED-IN  DUP  -1  =  IF  EXIT  ENDIF  DUP  RSEC  ! 

TIMED-IN  DUP  -1  =  IF  EXIT  ENDIF 
255  XOR  <>  IF  -1  ELSE  0  ENDIF  ; 

:  RCV-SECT  0  CXSUM  C!  12B  0  DO  TIMED-IN  DUP  -1  =  IF  EXIT  ENDIF 
DUP  XFER  7BUFFER-ADDR  I  +  C!  CXSUM  C8  +  CXSUM  C! 

LOOP  0  : 

--> 


Screen  #  12 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

:  RCV-CXSUM  TIMED-IN  DUP  -1  = 

IF  EXIT  ENDIF 
CXSUM  CS  = 

IF  0  ELSE  -1  ENDIF  ; 

:  SAVE-SECT  XFER  NRITE-SEQ  0= 

IF  .'  Can’t  write  sector.'  CR  ABEND  SUIT 


(Continued  on  page  81 ) 
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SEND  and  RCV  -  Listing 

(Listing  continued,  text  begins  on  page  66) 


ENDIF 

XSEC  3  .  .”  written. *  CR  1  XSEC  +!  ; 

:  DISP-CHR  BASE  3  >R  CR  DUP  HEX  2  .R  R>  BASE  ! 

HI"  EMIT  .'  !  unexpectedly  seen.  '  ; 


Screen  #  13 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

:  RCV  RCV-SETUP 

GOBBLE  Initial  NAK  sent.”  CR  NAK  XOUT 
BEGIN  7TERMAB0RT  IF  ABEND  QUIT  ENDIF  (  use  Ctrl-X  to  abort  ) 
TIMED-IN 

DUP  NUL  =  IF  DROP  RESTART  ENDIF 

DUP  CAN  =  IF  DROP  ."  Remote  Cancel.”  CR  ABEND  QUIT  ENDIF 

DUP  EOT  =  IF  DROP  NOREND  QUIT  ENDIF 

DUP  -1  =  IF  DROP  .”  T-”  RCVERR  RESTART  ENDIF 

DUP  SOH  <>  IF  DISP-CHR  RCVERR  RESTART  ENDIF  DROP 
RCV-HDR  IF  .”  H-”  RCVERR  RESTART  ENDIF 

RCV-SECT  IF  .”  S-”  RCVERR  RESTART  ENDIF 

RCV-CKSUM  IF  .”  C-”  RCVERR  RESTART  ENDIF 

SAVE-SECT  ACK  XOUT  0  NAK-CT  ! 

AGAIN  ;  --> 


Screen  #  14 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

:  HAIT-ACK  0  ERRS  !  (  --  ;  wait  for  ACK  or  CAN,  w /  tiling  ) 

BEGIN  ERRS  3  MAXERR  >  NAK-CT  3  MAXERR  >  OR 
IF  .”  Exceeded  Maximum  errors.”  CR  CAN  XOUT 
ABEND  QUIT  ENDIF 

7TERMAB0RT  IF  ABEND  QUIT  ENDIF  (  AX  7  ) 
TIMED-IN  CASE 

-1  OF  1  ERRS  +!  .”  Tiweout”  CR  ENDOF 
CAN  OF  .”  Reiote  Cancel”  CR  ABEND  QUIT  ENDOF 
ACK  OF  0  NAK-CT  !  EXIT  ENDOF 
NAK  OF  1  NAK-CT  +!  EXIT  ENDOF 
(  ELSE!  DISP-CHR  0  ENDCASE 
AGAIN  ; 

:  READ-SECT  SSEC  3  XFER  32  +  !  XFER  READ-SEQ  0=  j 
--> 


Screen  #  15 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

:  SEND-HDR  t  —  ;  send  header:  SOH  sec-l  NOTtsec-II  ) 

SOH  XOUT 

SSEC  3  1+  255  AND  DUP  XOUT  255  XOR  XOUT 
.'  Sending  ”  SSEC  3  .  CR  ; 


CKSUM  C3  +  CKSUM  C!  LOOP  ; 

:  SEND-CKSUM  CKSUM  C3  XOUT  ;  (  --  ;  cksua=SUMCal 1  128  bytes!) 


Screen  #  16 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

:  END-SEND  (  --  ;  terminate  transmission,  wait  for  ACK  ) 
XFER  CLOSE-FILE  DROP 

BEGIN  CR  .”  Sending  EOT  -”  EOT  XOUT  NAIT-ACK 
NAK-CT  3  0= 

UNTIL  .”  act’d”  CR  ; 

:  SEND-SETUP 
1300  L0N6-TIME0UT 
XFER  FILENAME  DROP  CR  XFER  OPEN-FILE 
IF  .'  File  doesn’t  exist.  Exitting.”  CR  QUIT 
ENDIF 

XFER  OUT-NAME  .”  opened.  Size  is:  "  XFER  16  +  23  SNAP  2DUP  D. 

.”  C  128  M /  SNAP  0  <>  +  .  .”  sectors!”  CR 
128  XFER  14  +  !  0  SSEC  !  0  NAK-CT  !  ; 

— > 


Screen  #  17 

(  SEND  and  RCV  files  using  XMODEM  protocol  06/03/83  ) 

!  SEND  (  —  ;  uses  XMODEM  protocol  to  send  a  file  ) 

SEND-SETUP  (  get  file  rdy! 

SHORT-TIMEOUT  GOBBLE  LONG-TIMEOUT  !  clear  line  ) 

.'  Awaiting  Initial  NAK:  ” 

NAIT-ACK  CR  SHORT-TIMEOUT  (  wait  for  NAK! 

BEGIN  7TERMAB0RT  IF  ABEND  QUIT  ENDIF  (  Ctrl-X  hit?  ! 

READ-SECT  IF  END-SEND  QUIT  ENDIF  (  at  end  of  file7  ! 
SEND-HDR  !  send  header  ) 

SEND-SECT  (  "  sector  ) 

SEND-CKSUM  (  ■  checksum  ) 

NAIT-ACK  NAK-CT  3  0=  (  ACK  rcv’d7  ) 

IF  1  SSEC  +!  ENDIF  (  yes,  incr.  Sec  I) 

AGAIN  ; 


End  Listing 


:  SEND-SECT  !  —  ;  send  each  byte  of  128  byte  sector.  ) 
0  CKSUM  C! 

128  0  DO  XFER  7BUFFER-ADDR  I  +  C3  DUP  XOUT 
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Precompiled  Forth 
Modules 


A  Forth  compilation  is  a  relatively 
slow  process.  In  the  system  I  use 
—  a  standard  Fig-Forth78*  running 
on  an  old  OSI  video  machine  —  my  full¬ 
screen  editor  occupies  35  screens  and 
takes  more  than  three  minutes  to  load 
and  compile.  This  is  intolerably  long  for 
production  programs.  As  a  result,  I  have 
developed  another  way  of  loading  pro¬ 
grams  through  the  use  of  precompiled 
modules.  The  main  idea  behind  my  ap¬ 
proach  is  to  treat  a  precompiled  module 
as  a  separate  vocabulary.  Thus,  each  over¬ 
lay  has  a  header  (analogous  to  a  vocabu¬ 
lary  header)  that  contains  the  information 
needed  by  the  module  loader  for  linking 
the  module  dictionary  with  the  Forth 
dictionary. 

The  source  code  for  the  words  imple¬ 
menting  overlays  is  contained  in  Listing 
One  (page  84).  I  should  mention  here 
that  my  editor  includes  a  command  for 
calculating  checksums  as  described  by 
Suralis  and  Brodie.1  The  CRC-16  check 
value  is  automatically  inserted  in  line  0  of 
each  screen.  I  have  also  followed  my  own 
recommendations  concerning  Forth  pro¬ 
gramming  style.2 


by  N.  Solnfseff 


N.  Solntseff,  Unit  for  Computer  Science, 
McMaster  University,  Hamilton,  Ontario 
L8S  4K1. 


*1  have  stuck  to  the  original  Fig  model  and  im¬ 
plementation  because,  in  my  experience,  exten¬ 
sions  and  improvements  made  by  implementors 
introduce  non  trivial  problems  due  to  the  result¬ 
ing  lack  of  portability.  Of  the  half-dozen  ver¬ 
sions  of  Forth  for  OSI  and  Commodore  64 
computers  I  have  acquired,  all  claiming  full 
compatibility  with  the  Fig-Forth79  standard, 
none  are  100%  consistent  with  the  latter.  In  my 
opinion,  it  is  better  to  have  a  completely  speci¬ 
fied  model,  such  as  the  Fig-  Forth78  one,  and 
an  implementation  that  rigorously  adheres  to  it, 
than  an  improved  model  with  implementations 
that  vary  among  themselves.  This  avoids  the 
need  for  detective  work  to  establish  the  effect 
of  allegedly  standard  words.  In  the  case  of  the 
Fig- Forth  78  model,  a  distributor  of  an  applica¬ 
tion  vocabulary  need  only  supply  the  additional 
words  needed  to  extend  his  or  her  system  to 
the  required  level. 


The  header  consists  of  a  vocabulary 
pseudo  name-field  81A0  followed  by  the 
link  field,  which  contains  the  name-field 
address  of  the  topmost  Forth  word  at  the 
time  the  overlay  header  is  created  (the 
value  of  LATEST).  Next  come  the  num¬ 
ber  of  screens  occupied  by  the  compiled 
overlay  words,  the  value  of  FENCE  for 
the  overlay,  the  name-field  address  of  the 
topmost  overlay  word,  and  finally  the  ad¬ 
dress  of  the  top  of  the  dictionary  including 
the  overlay.  Overlay  headers  are  created 
by  OVSTART  (Screen  31).  The  accom¬ 
panying  figure  (page  83)  illustrates  the 
function  of  the  overlay  header  and  shows 
the  dictionary  configuration  after  an 
overlay  has  been  loaded  into  memory. 

To  prepare  an  overlay,  the  user  calls 
MAKE-OVERLAY  (Screen  35),  supply¬ 
ing  the  number  of  the  first  screen  con¬ 
taining  the  source  code  of  the  program  to 
be  made  into  an  overlay.  This  creates  an 
overlay  header,  after  which  an  <n> 
LOAD  is  executed  to  load  and  compile 
the  program  into  memory.  Either  Screen 
<n>  should  be  a  master  screen,  which 
loads  the  rest  of  the  program,  or  the 
screens  should  be  linked  together  by 
means  of  the  word  -->.  After  the  pro¬ 
gram  is  loaded,  OVEND  (Screen  32) 
determines  how  many  screens  of  binary 
information  are  needed  to  store  the  over¬ 
lay  and  completes  the  header  by  storing 
the  values  of  FENCE,  HERE,  and  LATEST 
in  the  appropriate  header  locations.  After 
preparing  an  overlay,  the  user  can  store  it 
on  disk  by  invoking  <n>  PUT  (Screen 
33).  The  responsibility  of  ensuring  that 
sufficient  empty  screens  are  available  on 
disk  for  storage  is  left  to  the  user.  PUT 
checks  the  screens  to  see  if,  in  fact,  they 
contain  overlay  code  and  aborts  if  this  is 
not  the  case.  The  check  is  performed  by 
the  word  ?OV. 

Once  an  overlay  module  is  stored  on 
disk,  it  can  be  loaded  ready  for  execution 
by  means  of  the  word  GET  (Screen  34). 
GET  loads  several  consecutive  screens 
after  checking  that  the  first  screen  is 
indeed  an  overlay  preceded  by  an  overlay 
header;  GET  aborts  if  this  is  not  the  case. 
Its  last  action  is  to  set  the  vocabulary 
pointer  CURRENT  and  FENCE  to  pro¬ 
tect  the  loaded  overlay.  GETS  is  a  con¬ 
venience  word  that  can  be  used  to  load 
specific  overlays  by  name.  For  example, 
I  have  defined  the  word  EDITOR  to  load 
my  full-screen  editor  so  that  I  do  not 
have  to  remember  the  numbers  of  the 
screens  containing  its  overlay.  An  overlay 


is  easily  removed  by  invoking  the  routine 
EMPTY  (Screen  30),  which  clears  the 
user  dictionary  down  to  the  original 
Forth  system  portion. 

The  overlay  facility  has  proved  to  be 
indispensable.  The  editor  now  loads  in 
under  three  seconds  —  a  reduction  in 
loading  time  approximately  by  a  factor  of 
60!  A  word  of  caution  is  needed  here: 
Once  you  have  loaded  and  compiled 
Screens  30-35,  you  must  make  all  the 
overlay  words  a  permanent  part  of  the 
Forth  system,  so  that  they  are  available 
after  a  cold  start  and,  more  importantly, 
are  protected  by  the  system  FENCE. 
This  precaution  is  necessary  because  over¬ 
lays  always  start  immediately  after  the 
Forth  system  part  of  the  dictionary.  As 
this  procedure  is  highly  operating  system 
dependent,  I  will  leave  you  to  figure  out 
what  must  be  done  for  your  operating 
system.  Finally,  I  would  recommend  that 
the  word  .LINE  be  redefined  if  overlays 
are  used  extensively,  to  prevent  binary 
bytes  from  being  treated  as  control  char¬ 
acters  by  the  display  and  printer  drivers. 


Glossary 

?OV  <addr>  - 

Issue  an  error  message  (number  9)  if  the 
location  with  address  <addr>  does  not 
contain  the  start  of  an  overlay  header. 
Execution  of  the  word  containing  ?OV  is 
aborted. 

EMPTY 

Clear  the  user  part  of  the  dictionary 
down  to  the  topmost  Forth  definition. 
Both  the  value  of  FENCE  and  the  pointer 
to  the  top  name  in  the  word  FORTH  are 
reset  to  their  cold-start  values. 

FWAUD  -  <addr> 

Leave  the  address  of  the  start  of  the  user 
dictionary  on  the  data  stack.  This  is  the 
starting  address  of  all  overlays. 

GET  <n>  - 

Read  a  sequence  of  binary  screens  start¬ 
ing  with  Screen  <n>  and  place  the  over¬ 
lay  into  memory  starting  at  the  location 
given  by  FWAUD. 

GETS 

A  defining  word  used  in  the  form 
<n>  GETS<name> 
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Precompiled  Forth  Modules 

(Text  begins  on  page  82) 


SCR  #  30 

0  (  40801  —  overlays  —  FWAUD  NTOP  ?0V  EMPTY  30/  NS/10may83) 

1 

2  FORTH  DEFINITIONS  HEX 

3 

4  :  FWAUD  1C  +ORIGIN  @  ;  (  address  of  start  of  user  dictionary) 

5  :  NTOP  0C  +0RIGIN  @  ;  (  address  of  last  word  in  empty  UD) 

6 

7  :  ?0V  (  addr  —  ;  check  if  an  overlay  begins  at  addr) 

8  (  addr)  @  A081  -  09  TERROR  ; 

9 

10  :  EMPTY  (  —  ;  clear  user  dictionary  up  to  topmost  FORTH  word) 

11  [COMPILE]  FORTH  DEFINITIONS 

12  NTOP  '  FORTH  4  +  !  (  reset  NTOP  in  FORTH  vocab.) 

13  FWAUD  DUP  FENCE  !  (  reset  FENCE  to  original  value) 

14  (  fwaud)  DP  !  ;  (  reset  dictionary  pointer) 

15  — > 


SCR  #31 

0  (  60325  --  overlays  —  0VSTART  31/  NS/10may83) 

1 

2  :  0VSTART  (  —  ;  initialize  overlay  header) 

3  EMPTY  HERE  (  remove  all  user-defined  words) 

4  (  top)  A081  ,  (  create  a  dummy  vocabulary  header) 

5  (  top)  LATEST  ,  (  save  nfa  of  topmost  FORTH  word) 

6  (  top)  CURRENT  @  !  (  reset  vocabulary  pointer) 

7  0000  ,  (  space  for  number  of  screens  in  overlay) 

8  0000  ,  (  space  for  value  of  FENCE  for  overlay) 

9  0000  ,  (  space  for  top  of  dictionary  for  overlay) 

10  0000  ,  ;  (  space  for  nfa  of  topmost  overlay  word) 

11 

12  — > 

13 

14 

15 


SCR  #  32 

0  (  30432  —  overlays  —  OVEND  32/  NS/10may83) 

1 

2  :  OVEND  (  —  ;  complete  overlay  header  after  program  LOAD) 

3  CR  FWAUD  (  get  starting  addr  of  overlay) 

4  (  fwa)  HERE  FWAUD  -  B/BUF  /MOD  (  find  number  of  screens) 


5  (  fwa  n  rem)  SWAP  IF  1+  ENDIF 

6  (  fwa  # scr)  DUP  .  screens 

7  (  fwa  # scr)  OVER  4  +  ! 

8  (  fwa)  FENCE  @  OVER  6  + 

9  (fwa)  HERE  OVER  8  + 

10  (  fwa)  LATEST  OVER  0A  + 

11  (  fwa)  DROP  ; 

12 

13  — > 

14 

15 


(  adjust  number) 
required  by  overlay"  CR 

(  and  store) 
!  (  store  overlay  FENCE) 
!  (  store  overlay  HERE) 
!  (  store  overlay  LATEST) 
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33/  NS/llmay83) 


SCR  #  33 

0  (  40998  —  overlays  —  OVSAVE 
1 

2  :  PUT  (  n  —  ;  save  overlay  to  disc  starting  with  screen  n) 

3  (  n)  FWAUD  ?0V  (  get  fwa  of  save  &  check) 

4  (  n)  FWAUD  4  +  @  (  get  no  of  screens  needed) 

5  (  n  #bl)  0  DO  (  repeat  over  blocks) 

6  (  n)  DUP  FWAUD  I  B/BUF  *  +  (  get  from  address) 

7  (  n  from)  OVER  I  +  DUP  .  OFFSET  @  +  (  form  block  #) 

8  (  n  from  serf)  BUFFER  (  get  to  address) 

9  (  n  from  to)  B/BUF  CMOVE  (  move  to  disc  buffer) 

10  (  n)  UPDATE  FLUSH  (  write  to  disc) 

11  (  n)  LOOP  (  until  all  screens  are  read) 

12  (  n)  DROP  CR  ; 

13  — > 

14 

15 


SCR  #  34 

0  (  41428  —  overlays  —  0VL0AD  34/  NS/llmay83) 

1 

2  :  GET  (  n  —  ;  load  overlay  starting  with  screen  n) 

3  (  n)  DUP  .  (  echo  screen  number) 

4  (  n)  DUP  BLOCK  DUP  ?0V  (  read  screen  n  into  buffer) 

5  (  n  bufad)  DUP  8  +  @  DP  !  (  make  room  for  overlay) 

6  (  n  bufad)  DUP  FWAUD  B/BUF  CMOVE  (  move  first  block) 

7  (  n  bufad)  4  +  @  1  -  -DUP  (  get  number  of  sefeens  and  check) 

8  (  n  # sc-1)  IF  (  more  than  one  screen  used) 

9  (  n)  1+  1  DO  DUP  I  +  DUP  .  BLOCK  (  read  screen) 

10  (  n  from)  I  B/BUF  *  FWAUD  +  B/BUF  CMOVE  (  move) 

11  (  n)  LOOP  DROP  (  until  all  screens  read) 

12  ENDIF  CR 

13  FWAUD  0A  +  @  CURRENT  !  (  set  vocabulary  pointer) 

14  FWAUD  6  +  @  FENCE  !  ;  (set  overlay  FENCE) 

15  DECIMAL  — > 


SCR  #  35 

0  (  14136  --  overlays  —  MAKE-OVERLAY  PUT  GET  GETS  35/  NS/llmay83) 
1 

2  :  MAKE-OVERLAY  (  n  —  ;  LOAD  screen  n  and  prepare  overlay) 

3  (  n)  OVSTART  LOAD  OVEND  ; 

4 

5  :  GETS  (  defining  word:  n  GETS  <name>  ) 

6  (at  run  time,  <name>  performs  an  n  GET  ) 

7  <BUILDS  , 

8  D0ES>  @  GET  ; 

9 

10 

11 

12 

13 


14 


15 
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Signed  Integer  Division 


Not  all  methods  of  integer  division 
produce  a  uniform  result  when  the 
dividend  and  divisor  have  opposite 
signs.  This  may  not  be  so  important  in 
the  area  of  commerce  where  negative 
values  are  perhaps  used  less.  When  dealing 
with  measurement  and  control,  however, 
uniformity  becomes  more  significant.  The 
Forth  83  Standard  adopts  a  method  for 
signed  integer  division  called  “floored” 
division.  While  APL  has  used  this  method 
for  the  RES  function  for  years  and  Small¬ 
Talk  provides  it  as  one  of  three  methods 
for  integer  division,  acceptance  of  the 
Standard  makes  Forth  the  first  “popular” 
language  to  embrace  this  method  based 
on  its  theoretical  merits.  The  problem  is 
one  of  mathematical  purity  versus  user 
expectation.  This  article  will  attempt  to 
clarify  some  of  the  issues  involved. 

Integer  division  is  a  mathematical 
function  of  two  integers  (a  dividend  and 
a  divisor)  that  yields  an  integer  quotient 
and  an  integer  remainder.  That  appears  to 
be  a  fairly  straightforward  operation,  but 
there  is  not  universal  agreement  of  the  de¬ 
sired  results  when  one  or  both  arguments 
are  negative.  When  an  integer  quotient  is 
used  in  plotting  or  machine  control,  the 
desired  function  is  usually  not  the  quo¬ 
tient  given  by  the  majority  of  computers. 

Most  computers  with  a  divide  func¬ 
tion  produce  a  quotient  that  has  a 
property  of  symmetry  around  zero  when 
plotted  as  a  function  of  the  dividend,  due 
to  the  fact  that  the  quotient  is  rounded 
toward  zero.  Speaking  mathematically, 
the  property  is  actually  one  of  anti¬ 
symmetry,  where  the  sign  of  the  quotient 
is  reversed  when  the  sign  of  the  dividend 
(or  numerator)  is  reversed.  For  integer 
division,  this  “symmetric”  property  leads 
to  a  sort  of  discontinuity  around  zero.  In 
this  case,  the  remainder  is  either  zero  or  it 
takes  the  sign  of  the  dividend.  Figure  la 
(at  right)  illustrates  the  quotient  q  as  a 
function  of  a  variable  dividend,  and  a 
constant  divisor  3.  We  readily  see  the  dis¬ 
continuity  near  zero.  This  may  be  reason¬ 
ably  serious  when  this  quotient  function 
is  used  for  plotting  or  moving  robot  arms. 


by  Robert  L.  Smith 


Robert  L.  Smith,  ESL,  Inc.,  495  Java  Dr., 
Sunnyvale,  California  94086. 


86 


Dr.  Dobb’s  Journal,  Number  83,  September  1983 

533 


The  integer  quotient  needs  an  asso¬ 
ciated  remainder: 

r  =  n  -  q*d 

where  n  is  the  numerator  or  dividend,  d  is 
the  denominator  or  divisor,  q  is  the  quo¬ 
tient,  and  r  is  the  remainder.  The  remain¬ 
der  function  for  the  constant  divisor  3  is 
illustrated  in  Figure  lb  (page  86).  If  we 
look  at  the  case  of  positive  dividends  and 
divisors,  we  observe  the  cyclic  property 
that 

r(n  +  d)  =  r(n) 

In  other  words,  the  remainder  usually  has 
a  repeating  or  cyclical  property  as  the  di¬ 
vidend  changes.  For  the  remainder  shown 
in  Figure  lb,  we  see  that  this  simple 
property  is  not  maintained  for  dividends 
between  -d  and  0. 

If  we  require  that  the  remainder  be 
cyclical,  then  the  quotient  no  longer  has 
any  unusual  discontinuities.  There  are  a 
number  of  possible  choices  here.  One  ob¬ 
vious  choice  is  to  make  the  remainder  the 
same  as  the  modulus  or  residue  function.1 
In  this  case  the  quotient  is  rounded  to¬ 
ward  minus  infinity.  This  rounding  pro¬ 
cedure  is  called  the  “floor”  function. 
Figure  2  (page  86)  shows  the  floored 
quotient  and  its  related  modulus  for  the 
same  arguments  used  in  Figure  1.  Notice 
the  quotient  behaves  in  a  more  nearly 
continuous  fashion  around  zero.  This  is 
the  form  used  in  the  Forth-83  Standard, 
as  well  as  some  of  the  older  versions  of 
Forth.  The  National  16032  microproc¬ 
essor  produces  floored  division  in  addi¬ 
tion  to  the  older  “rounded  toward  zero” 
variety.  The  modulus  function  is  called 
MOD  in  Forth-83  and  in  the  National 
16032.  It  is  called  RES  in  APL. 

The  “floored”  quotient  shown  in 
Figure  2  is  not  anti-symmetric  around 
zero.  However,  for  odd  divisors  one  may 
easily  obtain  a  symmetric  result  by  adding 
a  correction  factor  to  the  dividend  prior 


to  division.  Although  the  quotient  is 
generally  not  defined  when  the  divisor  is 
zero,  the  modulus  is  usually  defined  to 
take  the  value  of  the  dividend  for  this 
case.  If  infinities  are  not  allowed  in  com¬ 
puter  representations,  and  the  product  of 
any  number  and  zero  is  always  zero,  then 
this  definition  preserves  the  equation 

n  =  q*d  +  r 

for  all  values  of  d,  including  zero. 

Alternative  remainder  functions  in¬ 
clude  a  positive  modulus  and  a  remain¬ 
der  that  takes  the  sign  of  the  quotient.2 
Some  other  possibilities  have  the  unde¬ 
sirable  feature  of  negative  remainders 
when  the  dividend  and  divisor  are  both 
positive. 

Floored  division  is  simply  more  use¬ 
ful  in  the  majority  of  applications  pro¬ 
grams.  The  major  objection  is  that  the 
results  are  not  what  most  people  expect: 
-1  divided  by  4  gives  0  in  the  rounded- 
toward-zero  division  case,  but  -1  for 
floored  division.  Both  cases  give  the  same 
results  when  the  dividend  and  divisor 
have  the  same  sign.  Timing  efficiencies 
may  play  a  small  role  in  deciding  which 
form  of  division  to  use,  but  generally  the 
division  process  is  sufficiently  slow  that 
additional  tests  for  different  forms  of 
rounding  take  only  a  little  extra  time. 
Indeed,  for  some  processors  with  built-in 
signed  and  unsigned  divide  functions,  it 
may  be  faster  in  the  common  case  of 
positive  arguments  to  test  signs  and  use 
the  unsigned  division  than  to  just  use  the 
signed  division  function.  If  you  have  an 
older  Forth  system  (such  as  79-Standard 
or  Fig-Forth),  the  screen  in  Figure  3 
(page  88)  shows  a  high-level  conversion 
from  the  older  form  of  /MOD  to  the 
newer  version.  For  those  unfamiliar  with 
Forth,  /MOD  takes  two  arguments,  the 
dividend  and  the  divisor,  and  returns  two 
results:  the  quotient  and  the  modulus,  or 
remainder.  The  quotient  is  returned  as 


the  most  accessible  element  on  the  stack. 

The  appearance  of  floored  division  in 
some  of  the  newer  processor  chips  and 
languages  indicates  the  increasing  aware¬ 
ness  of  its  utility.  We  might  note  in  pass¬ 
ing  that  even  floating-point  division  will 
probably  be  different  in  the  future  than 
it  was  in  the  past  due  to  the  new  Floating- 
Point  Standard,  which  will  require  proper 
rounding  of  the  quotient. 
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(  Define 

83-Standard  /MOD 

in  terms  of  old  /MOD  ) 

:  /MOD 

(  num  den 

mod  quot  ) 

OVER  OVER  XOR  0< 

(  test  signs  of  arguments  ) 

IF 

(  signs  are  different  ) 

>R  R@  /MOD  OVER  (  divide  and  examine  remainder  ) 

IF 

(  non-zero  remainder  ) 

1-  SWAP 

R>  +  SWAP  (  adjust  results  ) 

ELSE 

(  zero  remainder  ) 

R>  DROP 

THEN 

(  discard  old  den  ) 

ELSE 

(  signs  the  same  ) 

/MOD 

(  just  divide  normally  ) 

THEN  ; 

(  end  of  definition  ) 

Figure  3. 

High  Level  Forth  Code  to  Convert  to  Floored  Division 
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When  a  Page  Is  Not  a  Page: 

Forth-83  and  Vocabularies  x 


One  of  the  most  frustrating  chores 
in  writing  a  program  is  not  deter¬ 
mining  the  algorithms  (that’s  a 
challenge)  but  naming  the  procedures  and 
program  structures  so  that  the  program 
reads  and  makes  sense.  Most  BASIC 
programmers  don’t  have  this  problem 
because  the  relationship  of  the  variable 
name  B3  to  its  usage  is  just  as  nonexistent 
as  the  relationship  of  line  number  950 
to  the  function  of  the  procedure  on  that 
line.  When  you  have  30  or  so  characters 
at  your  disposal,  you  can  pick  just  about 
any  word  names  you  want.  The  problem 
comes  in  thinking  up  appropriate,  read¬ 
able  names. 

Generally,  the  shortest  word  possible, 
so  long  as  the  word  remains  appropriate, 
will  be  easiest  to  use  and  read.  Compound, 
long,  or  abbreviated  words  (especially 
acronyms)  only  make  the  program  harder 
to  read  and  follow.  Given  that  most  of  us 
probably  did  not  major  in  English  in  col¬ 
lege,  our  working  vocabulary  is  generally 
limited  to  an  amazingly  few  thousand. 
Since  most  processes  are  named  with 
appropriately  descriptive  verbs,  the  list 
becomes  even  smaller. 

Vocabularies 

The  naming  problem  is  solved  within 
the  English  language  by  words  having 
context-dependent  meanings.  Take  the 
word  page,  for  instance.  Depending  on 
context,  page  can  take  on  any  of  the 
following  meanings: 

an  errand  boy  or  messenger;  to  summon 
by  calling  the  name  of;  a  leaf  of  a 
book  or  manuscript  or  one  side  of  it; 
to  number  the  pages  of,  paginate;  to 
thumb  through.1 

Additionally,  when  referring  to  memory 
in  computer  jargon,  a  page  is  some  power 
of  two  bytes  such  as  256,  1024,  4096,  and 
so  on.  It  is  difficult  enough  for  people  to 
determine  what  is  meant  by  a  sentence 
(i.e.,  what  do  I  mean  when  I  say,  “The 
page  moved”?)  without  trying  to  pro¬ 
gram  the  computer  to  do  the  same.  In 
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fact,  on  most  Forth  systems  PAGE  is 
defined  as  performing  a  form  feed  (on 
printers)  or  clearing  the  screen  (on  video 
terminals). 

Forth  uses  a  simple  approach  to  select 
one  of  several  different  meanings  for  the 
same  word  (letter  group).  Rather  than 
making  each  word  very  complicated  by 
trying  to  have  the  word  determine  which 
meaning  was  desired,  Forth  allows  the 
programmer  to  separate  words,  even 
those  which  have  the  same  names,  into 
(usually)  contextual  groups  referred  to  as 
vocabularies.  Each  vocabulary  is  simply 
a  list  of  words  that  can  be  selected  by 
name. 


How  to  Use  Vocabularies 

Vocabularies  are  simple  to  create  and 
use.  Executing  the  phrase 

VOCABULARY  FILE 

creates  a  word  in  the  dictionary  within 
the  compilation  vocabulary  (the  one  to 
which  words  are  being  added)  named 
FILE  that,  when  executed,  will  make  a  list 
of  words  available  to  the  system.  Creating 
the  FILE  vocabulary  does  not  select  the 
FILE  list  of  words  (which  is  currently 
empty).  Executing  the  phrase 

FILE  DEFINITIONS 

selects  the  FILE  list  of  words  to  be 
searched  and  then  tells  the  system  that 
this  is  where  new  word  definitions  will  be 
placed.  Executing  the  word  DEFINI¬ 
TIONS  makes  the  last  vocabulary  exe¬ 
cuted  (in  this  case  FILE)  the  compilation 
vocabulary. 

So,  to  create  a  vocabulary,  make  it 
available,  and  place  word  definitions  in 
it,  we  would  execute: 

VOCABULARY  FILE  IMMEDIATE 

FILE  DEFINITIONS 

The  word  IMMEDIATE  marks  the  last 
word  created  as  a  word  to  be  executed 
during  compilation.  In  this  case,  execu¬ 
tion  during  compilation  would  select  the 
FILE  vocabulary  enabling  us  to  access  the 
FILE  words.  All  words  defined  after  exe¬ 
cuting  the  above  will  be  placed  in  the 
FILE  vocabulary  until  another  vocabu¬ 
lary  name  and  the  word  DEFINITIONS  is 
executed. 

Suppose  now  we  wish  to  define  a 
word  to  build  a  file  entry  into  the  direc¬ 
tory  on  the  disk.  Let’s  see  .  .  .  what  name 
should  we  use  to  create  a  file?  Think 
about  it.  How  about  CREATE?  But  there 


is  one  small  problem.  The  FORTH  vocab¬ 
ulary  already  has  defined  the  word  CRE¬ 
ATE  to  build  names  into  the  dictionary. 
The  solution  is  to  use  the  FILE  vocabu¬ 
lary  we  defined  above: 

FILE  DEFINITIONS 

(  we  defined  FILE  above  ) 

:  CREATE  ....  ; 

(  “....”  are  your  words  that 
define  how  to  build  a  file  ) 

Now  to  create  a  file  we  can  simply  type: 

_ FILE  CREATE _ 

(  “.  .  .  .”  are  words,  or  stack  or 
other  data  ) 

Reads  nicely,  doesn’t  it?  It  also  saves 
memory  over  other  naming  options  such 
as  FILE-CREATE,  if  other  file  operation 
words  are  going  to  be  defined  and  the 
FILE-  is  going  to  be  repeated. 


Search  Order 

The  Forth-83  Standard  introduces 
the  concept  of  search  order  to  Standard 
Forth  systems.  The  search  order  is  the 
order  in  which  selected  vocabularies  in  the 
dictionary  are  searched.  Unfortunately, 
because  the  many  different  ways  of  im¬ 
plementing  vocabularies  have  varying 
merits,  no  Standard  has  yet  been  defined 
for  specifying  the  search  order.  The  cur¬ 
rent  document  only  tells  us: 

The  search  order  begins  with  the  last 
vocabulary  executed  and  ends  with 
FORTH,  unless  altered  in  a  system  de¬ 
pendent  manner.2 

This  acknowledges  that  Forth  systems 
have  the  ability  to  change  the  search 
order,  but  that  this  cannot  be  performed 
in  a  standard  way  as  yet. 

So  currently  a  Forth-83  Standard 
System  searches  two  vocabularies  (at 
most)  during  a  dictionary  search:  the  vo¬ 
cabulary  last  executed  and  then  FORTH. 
Note  that  this  is  not  a  strict  rule.  The  sys¬ 
tem  must  simply  behave  as  if  this  were 
the  case  to  remain  compatible  with  other 
systems.  What  is  actually  done  is  up  to 
the  implementor;  the  Standard  only  spe¬ 
cifies  the  apparent  behavior  of  the  system. 
Also  note  that  the  compilation  vocabu¬ 
lary  (formerly,  in  Fig-Forth,  this  was  the 
CURRENT  vocabulary)  is  not  necessarily 
part  of  the  search  order  as  it  always  is  in 
Fig-Forth. 

An  Experimental  Proposal 

All  hope  is  not  lost  for  search  order 
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specification  in  a  Standard  System.  The 
Forth  Standards  have  a  provision  for  the 
proliferation  of  good  but  unproven  or  not 
widely  used  ideas  that  are  candidates  for 
future  standardization.  These  are  called 
experimental  proposals.  One  such  experi¬ 
mental  proposal  that  has  been  accepted 
from  William  F.  Ragsdale  is  entitled 
“Search  Order  Specification  and  Control” 
(based  on  his  paper  “The  ONLY  Concept 
for  Vocabularies”3).  The  proposal  de¬ 
scribes  a  small  set  of  words  for  specifying 
and  controlling  the  search  order. 

The  proposal  suggests  the  addition  of 
five  words  to  the  Standard  to  manipulate 
and  display  the  search  order:  ALSO, 
ONLY,  SEAL,  ORDER,  and  WORDS. 
The  first  three  are  used  to  manipulate  the 
search  order  and  the  last  two  are  used  for 
display  purposes.  Additionally,  individual 
vocabularies  are  sealed  rather  than  chained 
as  in  Fig-Forth  and  are  usually  defined  as 
nonIMMEDIATE  (depending  upon  usage). 

In  Ragsdale’s  implementation,  the 
search  order  consists  of  up  to  five  vocabu¬ 
laries,  with  the  top  location  being  replaced 
(without  affecting  the  others)  each  time  a 
vocabulary  name  is  executed.  Thus  there 
are  up  to  four  permanent  positions  and 
one  transient  position.  The  vocabulary  in 
the  transient  position  is  added  to  the  per¬ 
manent  search  order  by  executing  ALSO. 
The  search  order  is  cleared  to  a  minimum 
set  of  words  (those  for  vocabulary/search 
order  manipulation  only)  by  executing 
ONLY.  A  typical  specification  of  the 
search  order  prior  to  compiling  an  appli¬ 
cation  might  be 

ONLY  FORTH  ALSO 

APPLICATION  DEFINITIONS 

where  FORTH  and  APPLICATION  are 
previously  defined  vocabularies.  The 
APPLICATION  vocabulary  is  where  the 
word  names  about  to  be  compiled  will  be 
added. 

The  word  ONLY  is  an  interesting  beast; 
it  is  actually  a  vocabulary  plus  some.  Its 
internal  structure  is  that  of  a  vocabulary, 
but  its  execution  procedure  does  what  a 
vocabulary  does  (placing  it  first  in  the 
search  order)  and  more.  ONLY  actually 
removes  all  vocabularies  from  the  search 
order  and  places  itself  both  in  the  bottom¬ 
most  permanent  position  and  on  top.  As 
a  vocabulary,  ONLY  usually  contains 
seven  to  ten  words  useful  in  manipulat¬ 
ing  vocabularies  and  the  search  order: 
FORTH,  DEFINITIONS,  VOCABULARY, 
WORDS,  FORGET,  ONLY,  ALSO,  and 
sometimes  SEAL  and  ORDER.  After 
ONLY  is  executed  the  above  words  are 
the  only  words  available.  In  the  following, 
we  step  through  the  previous  example: 

ONLY  —  clears  the  search  order  to 
minimum  words. 

FORTH  —  makes  this  vocabulary 
available. 


ALSO  —  keeps  the  transient  item  as 
permanent. 

APPLICATION  —  makes  this  vocabulary 
available;  it  must  have  been  de¬ 
fined  previously  within  FORTH  or 
ONLY  vocabularies. 

DEFINITIONS  —  causes  new  words  to 
become  part  of  APPLICATION 
vocabulary. 

It  is  very  useful  to  be  able  to  find  out 
what  the  current  search  order  is,  especial¬ 
ly  when  an  error  occurs  because  a  word 
name  has  not  been  found.  The  word 
ORDER  performs  this  job.  InTaskFORTH 
from  Shaw  Labs  (the  system  I  use  and  the 
only  system  being  sold  as  of  June  1983 
that  uses  Ragsdale’s  proposal),  the  exam¬ 
ple  above  would  print  as: 

Search: 

APPLICATION  FORTH  ONLY 
Compile: 

APPLICATION 

Also,  because  this  is  still  experimental, 
TaskFORTH  will  hold  a  search  order  of 
up  to  nine  vocabularies.  I  commonly  use 
six  and  sometimes  seven  vocabularies  in 
the  search  order.  I  like  to  use  lots  of  little 
vocabularies  (20  to  100+  words  in  each) 
for  independent  functional  areas  such  as 
CLOCK  (time/date),  DOCUMENT  (docu¬ 
mentation  help),  DEBUGGER’S  (debug¬ 
ging  versions  of  words),  and  FILE  (file 
system  functions)  among  others. 

Another  useful  search  order  function 
is  to  list  the  words  in  the  first  vocabulary 
in  the  search  order.  WORDS,  of  course, 
performs  this  function.  Used  by  itself, 
WORDS  lists  the  word  names  in  the  last 
vocabulary  executed;  to  see  the  list  of 
word  names  in  a  given  vocabulary,  simply 
execute  the  vocabulary  name  first.  For 
instance, 

EDITOR  WORDS 

will  list  the  word  names  in  the  EDITOR 
vocabulary.  The  command  sequence  reads 
nicely,  doesn’t  it?  (The  Fig-Forth  name 
for  WORDS  is  VLIST). 

The  last  word  name  in  Ragsdale’s 
experimental  proposal  is  SEAL.  This 
word  allows  the  application  to  have  com¬ 
plete  control  over  the  system  by  remov¬ 
ing  all  programming  words  from  the 
search  order.  So,  if  the  word  names  that 
should  be  available  to  the  user  are  availa¬ 
ble  in  the  vocabulary  COMMANDS,  then 
a  command  like 

ONLY  COMMANDS  SEAL 

will  make  COMMANDS  the  only  vocab¬ 
ulary  in  the  search  order  and  hence  the 
only  list  of  words  available  to  the  system. 

SEAL  actually  just  removes  ONLY 
from  the  bottom  position  in  the  search 
order  where  it  normally  resides.  To  step 
through  the  process  in  this  example, 
execution  of  the  following  commands 


will  produce  the  corresponding  results: 

ONLY  —  allows  access  to  the  nine  words 
it  contains  (COMMANDS  should 
be  a  part  of  the  ONLY  vocabulary). 

COMMANDS  -  makes  the  COMMANDS 
vocabulary  words  available. 

SEAL  —  removes  the  ONLY  vocabulary, 
leaving  the  COMMANDS  vocab- 
bulary  as  the  sole  set  of  words 
available. 

In  practice  this  can  be  useful  for  end-user 
applications.  Since  it  locks  the  operator 
out  of  the  rest  of  the  system,  one  may 
thereby  prevent  any  inadvertent  or  inten¬ 
tional  use  of  words  that  are  unrelated  to 
the  application,  which  could  cause  prob¬ 
lems. 

You  may  have  noticed  that  the  ex¬ 
perimental  proposal  doesn’t  include  a 
word  to  remove  a  vocabulary  from  the 
permanent  search  order.  This  was  deliber¬ 
ate  on  Ragsdale’s  part.  Ragsdale  views  the 
search  order  as  somewhat  more  sacred 
than  a  stack,  not  something  that  you 
arbitrarily  add  to  and  remove  from  (other 
than  in  the  transient  position).  He  believes 
that  if  the  permanent  search  order  is  to 
be  changed  you  should  start  over  with 
ONLY.  I  agree  that  you  should  not  try  to 
gain  the  efficiencies  of  a  stack  by  push¬ 
ing,  popping,  and  swapping  items.  But  my 
experience  has  indicated  that  I  sometimes 
can  simplify  my  program  (for  compila¬ 
tion)  by  temporarily  adding  a  permanent 
(semi- permanent?)  vocabulary  to  the 
search  order  and  then  removing  it.  This 
actually  just  saves  typing  or  sometimes 
increases  readability. 

The  word  I  use  for  this  function  is 
TOSS.  It  pulls  the  search  order  up  one 
slot  so  that  the  most  recently  placed 
permanent  vocabulary  moves  into  the 
transient  position  and  the  previous  trans¬ 
ient  vocabulary  is  lost.  I  use  this  either 
during  compilation  (as  described  above) 
or  from  the  keyboard  to  remove  a  vocab¬ 
ulary  that  has  been  ALSOed.  My  require¬ 
ment  probably  stems  more  from  my  use 
of  a  deeper  search  order  and  desire  to 
avoid  typing  five  or  six  vocabulary  names 
and  ALSOs  to  remove  one  or  more  from 
the  top. 

Conclusions 

Forth- 83  Standard  is  a  far  cry  from 
Forth-79  in  the  area  of  standardized 
vocabularies.  They  are  more  a  part  of  the 
Standard  and  seem  to  be  on  the  leading 
edge  of  development.  As  far  as  Standard 
usage  is  concerned,  however,  they  behave 
the  same  way  as  in  Forth-79,  which  is 
not  saying  much.  If  other  vendors  were 
to  incorporate  Ragsdale’s  experimental 
proposal  into  their  Forth  systems,  a  very 
powerful  search  order  mechanism  could 
by  default  become  a  required  “non¬ 
standard”  part  of  most  Standard  Systems. 
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The  Standard  seems  to  allow  this  through 
a  provision  for  “Environmental  Depen¬ 
dencies,”  although  this  provision  is 
directed  more  towards  hardware  than 
Forth  system  software  requirements.  If 
other  vendors  adopt  Ragsdale’s  proposal, 
the  Forth  community  could  benefit 
greatly. 
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Forth,  like  other  computer  languages, 
provides  a  formal  syntax  for  con¬ 
veying  commands  to  the  computer. 
However,  the  language  will  not  necessarily 
convey  this  information  to  another  pro¬ 
grammer  with  suitable  grace.  In  order  to 
convey  this  programmer-to-programmer 
information,  coding  standards  are  re¬ 
quired  to  ensure  that  the  information 
necessary  for  easy  understanding  is  pre¬ 
sented.  This  article  discusses  that  required 
information  and  some  different  styles  of 
its  expression. 

What  are  you  doing? 

In  order  to  use  Forth  effectively,  you 
must  first  ask  yourself  what  you  are 
doing,  and  what  you  want  to  accomplish. 
Are  you  trying  to  kill  a  half  hour  before 
M.A.S.H.?  Are  you  writing  game  software 
that  has  to  work,  but  nobody  needs  to 
see  inside?  Are  you  writing  a  Forth  sys¬ 
tem  that  you  wish  to  sell,  and  that  other 
people  must  be  able  to  use  and  modify? 
Depending  upon  what  you  are  doing,  you 
may  make  certain  decisions  about  how 
you  write  your  code. 

Why  coding  standards? 

Computer  programming  is,  in  a  sense, 
nothing  more  than  management  of  com¬ 
plexity,  where  ideas  are  the  underlying 
medium  of  the  complexity,  and  the  ideas 
are  expressed  in  a  code  peculiar  to  the 
system  you  are  using.  The  source  code 
tells  what  you  are  doing  at  a  very  detailed 
level,  which  is  fine  for  the  computer. 
People,  however,  require  big- picture 
information,  such  as  the  organization  of 
your  code  and  the  requirements  imposed 
by  that  organization.  Conforming  to  a 
coding  standard  should  guarantee  com¬ 
plete  information  on  this  organization, 
and  your  choice  of  complexity  manage¬ 
ment  techniques,  regardless  of  the  format 
used. 

Coding  standards  describe  various  as¬ 
pects  of  code  generation,  including  struc¬ 
ture,  modularization,  names  of  words 
(procedures),  comments,  and  layout  Df 
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typed  source  code.  Structure  and  modu¬ 
larization  are  the  same  in  Forth  as  in 
Pascal,  C,  Ada,  and  other  structured  lan¬ 
guages,  and  have  been  dealt  with  at  length 
in  standard  texts.  This  article  discusses 
aspects  more  peculiar  to  the  Forth  envi¬ 
ronment,  including  names,  comments  and 
layout. 

Names  of  Forth  Words 

English  is  a  powerful,  subtle,  compli¬ 
cated,  sophisticated,  yet  ambiguous  lan¬ 
guage.  For  a  native  speaker  of  English, 
Forth  provides  a  unique  facility  for  ex¬ 
pressing  ideas  to  a  computer.  Since  a 
Forth  word  is  invoked  (either  for  compi¬ 
lation  or  execution)  by  typing  its  name, 
the  name  is  a  logical  place  to  start  looking 
at  Forth  coding  standards. 

Long  vs.  Short 

A  major  bone  of  contention  is 
whether  one  should  use  long  word  names 
or  short  word  names.  The  comm  on -sense 
answer  is,  it  depends.  For  example,  if  you 
are  controlling  a  color  display,  you  might 
choose  to  have  words  with  names  like 

RED  BLUE  GREEN  BLACK 
WHITE  SET_FOREGROUND 
SET_BACKGROUND 

Another  choice  would  be  to  have  words 
like 

RED_BACKGROUND 

RED .FOREGROUND 
BLUE  .BACKGROUND 

BLUE.FOREGROUND 

GREEN.BACKGROUND 

GREEN .FOREGROUND 
BLACK .BACKGROUND 

BLACK .FOREGROUND 
WHITE.BACKG  ROUND 

WHITE.FOREGROUND 

or  perhaps 

RED  BACKGROUND  SET 

BLUE  FOREGROUND 

GREEN 

BLACK 

WHITE 

The  first  implementation  seems  to 
have  several  advantages:  the  color  words 
and  the  SET.  words  allow  you  to  choose 
your  own  combinations,  so  that  additions 
to  the  color  set  require  no  knowledge  of 
changes  in  the  SET.  commands,  and 
changes  to  the  SET.  commands  do  not 
affect  the  color  words.  By  comparison,  if 
you  had  to  change,  say,  the  .BACK¬ 
GROUND  part  in  the  second  set  of  words, 


you  would  have  five  words  to  change, 
rather  than  just  one.  The  total  length  of 
all  commands  is  shorter,  which  may  not 
be  important.  The  third  choice  may  be 
appropriate  in  some  situations. 

The  way  to  tell  which  alternative  to 
use  is  to  examine  the  underlying  parallel¬ 
ism  (if  any)  of  the  internals.  If  your  soft¬ 
ware  consists  of  various  parallel  modules 
with  very  similar  structure,  then  it  makes 
sense  to  use  short  words  with  parallel 
meanings,  such  as  RED,  BLUE,  GREEN 
as  one  set,  and  FOREGROUND  and 
BACKGROUND  as  another  set. 

Often  it  is  appropriate  to  use  longer 
word  names,  particularly  for  words  which 
both  cause  something  to  happen  (as 
opposed  to  those  related  to  memory 
structures)  and  are  specialized  to  the 
point  that  no  other  Forth  words  in  your 
system  will  perform  the  same  function. 
Some  examples  would  be 

RESET.LOG.FILE 

TRANSMIT.DATA  .PACKET 

These  longer  word  names  are  usually 
found  in  applications  software  (as  opposed 
to  systems  software),  and  in  the  higher 
levels  of  the  software  -  the  parts  that  call 
other  routines  to  do  the  smaller  tasks 
which  make  up  the  whole. 

Consider  another  set  of  words  which 
control  a  faucet: 

FAUCET  OPEN  CLOSE 

versus 

FAUCET. OPEN  FAUCET.CLOSE 

or 

OPEN. FAUCET  CLOSE. FAUCET 
Which  makes  more  sense?  Possibly,  the 
first  one  makes  more  sense  if  FAUCET 
specifies  what  is  to  be  affected  by  the 
command,  and  the  two  parallel  commands 
OPEN  and  CLOSE  operate  the  specified 
device.  If,  however,  OPEN  and  CLOSE 
can  work  only  on  FAUCET,  it  makes 
sense  to  consolidate  the  words  into 
OPEN -FAUCET  and  CLOSE- FAUCET. 

Word  Combinations 

For  those  situations  in  which  long 
names  are  appropriate,  a  good  idea  is  to 
start  the  long  name  with  a  verb.  In  the 
example  above,  SET.BACKGROUND 
starts  with  a  verb.  So  does  OPEN. 
FAUCET  —  or  does  it?  Does  OPEN. 
FAUCET  mean  “open  the  faucet”  or 
does  it  mean  “a  faucet  which  is  open”? 
Here  is  where  the  ambiguity  of  English 
can  make  things  interesting.  The  same 
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language  that  supports  an  especially  wide 
range  of  slang  expressions  and  that  is  rich 
enough  to  provide  enough  words  to  be 
the  world’s  de  facto  technical  language, 
has  enough  loopholes  to  let  you  write 
confusing  gibberish.  After  all,  it  may  not, 
for  your  application,  be  enough  that  you 
understand  what  you  are  writing  now,  or 
that  one  of  the  possible  ambiguous  mean¬ 
ings  makes  sense.  If  you  need  to  convey 
ideas,  ambiguities  can  do  you  in. 

There  is,  not  surprisingly,  another 
opinion.  That  opinion  is  that  the  verb 
should  end  the  name,  just  as  Forth  opera¬ 
tors  come  after  their  arguments  in  post¬ 
fix  notation.  For  example,  you  might 
write  FAUCET_OPEN,  or,  to  make 
it  more  English-like  and  less  Forth- 
ish,  FAUCET-OPENS  or  FAUCET_IS_ 
OPENED. 

In  my  experience,  verb  phrases,  such 
as  SET-BACKGROUND,  make  excellent 
names  for  Forth  words  that  cause  some¬ 
thing  to  happen.  For  Forth  words  that  are 
primarily  memory  access,  and  which 
generate  only  addresses  or  values,  noun 
phrases  and  nouns  are  appropriate, 
such  as  BUFFER-LENGTH  or  BYTES/ 
BLOCK. 

By  this  time,  you  have  probably 
noted  that  much  of  this  discussion  is 
about  writing,  and  not  particularly  about 
Forth.  If  you  are  concerned  with  trans¬ 
mitting  ideas,  writing  skills  are  as  impor¬ 
tant  in  Forth  as  technical  skills.1 

Abbreviations 

One  argument  that  comes  up  from 
time  to  time  in  the  long/short  name  con¬ 
troversy  is  the  time  spent  typing.  There  is 
no  doubt  that  long  names  will  take  longer 
to  type,  and  they  will  probably  take  up 
more  space,  too.  Often,  though,  this  is 
only  part  of  the  issue.  If  there  is  any  de¬ 
bugging  to  be  done,  or  if  the  code  must 
survive  over  time  or  be  accessed  by  multi¬ 
ple  programmers,  then  the  reading  and 
understanding  time  can  be  much  more 
important  than  the  typing  time.  On  the 
other  hand,  if  you  have  words  which  are 
used  frequently  enough  that  contractions 
can  be  remembered  easily,  then  these  con¬ 
tractions  may  be  appropriate.  After  all, 
the  Forth  words 

DUP  ROT 

are  widely  used  and  accepted,  rather  than 
the  more  formal 

DUPLICATE— TOP_OF_  STACK 

ROTATE— TOP_3_ON_ STACK 

There  is  a  pitfall  in  using  abbrevia¬ 
tions,  however.  If  you  use  different  abbre¬ 
viations  for  the  same  English  word  in  dif¬ 
ferent  Forth  words,  or  sometimes  abbrevi¬ 
ate  a  word  and  sometimes  not,  you  will 
probably  go  bonkers  trying  to  keep  the 
different  abbreviations  straight.  Consider, 
for  example 

ARDVK  -PRICE  ARDVRK— AGE 


AARD-WEIGHT  RDVRK-LENGTH 

Four  different  abbreviations  for  aardvark, 
and  which  abbreviation  goes  with  what? 
The  moral  of  this  story  is  that  anything 
abbreviated  once  must  always  be  abbre¬ 
viated,  and  always  in  the  same  way. 

Almost  every  programmer  optimizes 
his  code.  Some  optimize  for  speed,  some 
for  minimum  memory  usage,  some  for 
clarity  of  source  code.  If  you  optimize 
your  code  for  minimum  number  of  typed 
keystrokes,  make  sure  that  you  can 
afford  a  price  which  is  often  high  and 
seldom  predictable. 

Commenting  Your  Code 

If  you  ever  want  to  rile  your  acquain¬ 
tances  who  have  heard  of  Forth  but  don’t 
use  it,  tell  them  that  it  is  self-commenting 
(i.e.,  the  code  is  so  clear  that  no  comments 
are  required).  Then  show  them  some 
code  that  looks  like 

:  EUREKA!!!  OVER  >R  DP  HERE 
SWAP  !  SWAP  DROP  R>  SWAP  ; 

On  the  other  hand,  you  could  show  them 
code  such  as 

:  INITIALIZE— SCREEN 
CLEAR-SCREEN 
SET-UPPER— &-LOWER-CASE 
ENABLE-COLOR-OUTPUT  ; 

which  gives  a  reasonable  approximation 
to  self-documentation. 

In  both  of  these  examples,  however, 
there  is  a  shortcoming.  If  you  need  to  use 
EUREKA!!  or  INITIALIZE— SCREEN, 
what  inputs  do  you  provide?  What  out¬ 
puts  can  you  expect?  What  formats  do 
these  inputs  and  outputs  use?  In  Forth, 
words  are  really  procedures  that  cause 
some  sequence  of  steps  to  execute.  Many 
of  these  procedures  are  functions  in  the 
mathematical  sense,  with  a  domain  (set  of 
inputs)  and  a  range  (set  of  outputs).  If 
you  are  to  specify  this  function  complete¬ 
ly,  you  need  to  give  the  inputs  required, 
and  the  outputs  generated.  If  this  infor¬ 
mation  is  not  provided,  you  have  generated 
the  Forth  equivalent  of  a  graph  with  no 
labels  on  the  axes.  Maybe  you  knew  once 
what  the  graph  meant,  but  how  can  any¬ 
body  else  figure  it  out?  Will  you  remem¬ 
ber  it? 

To  solve  the  input/output  comment¬ 
ing  problem,  Fig  (the  Forth  Interest 
Group)  developed  a  set  of  stack  comments 
which  were  appropriate  for  their  needs  — 
specifically,  documenting  the  inputs  and 
outputs  to  the  basic  kernel  words.  Briefly, 
the  Fig  stack  comments  take  the  form 

(  a  b - c  ) 

which  means  that  a  and  b  are  inputs,  with 
b  (the  right-most  item)  on  top  of  the 
stack,  and  c  as  the  output.  In  the  Fig 
documentation,  the  types  (integer,  double 
integer,  byte,  etc.)  of  the  inputs  and  out¬ 
puts  are  specified,  rather  than  the  names 
of  the  inputs  and  outputs.  (See  the  Fig- 


Forth  Installation  Manual.2)  This  is 
appropriate  when  your  Forth  word  oper¬ 
ates  on  any  16-bit  address,  or  on  any 
true/false  flag,  or  on  any  byte. 

When  you  write  applications  soft¬ 
ware,  however,  you  are  attempting  to 
solve  a  different  set  of  problems,  and  the 
stack  comments  appropriate  to  that 
different  set  of  problems  may  also  be 
different.  For  example,  if  you  have  a 
complicated  Forth  word  with  four  inputs 
and  two  outputs,  commenting  that  these 
inputs  and  outputs  are  all  16 -bit  integers 
will  probably  not  be  very  useful.  For 
applications,  you  will  undoubtedly  want 
to  specify  the  names  of  the  inputs  and 
outputs.  If  your  names  are  multi-word, 
such  as  LEFT— MOTOR— RPM,  you  may 
put  dashes  (-)  or  underbars  (  _  )  between 
the  elements  of  your  long  input  and  out¬ 
put  names,  and  separate  these  long  names 
from  each  other  with  spaces.  If  you  use 
multi-word  names  and  use  spaces  to 
separate  the  elements  of  each  multi-word 
name,  you  will  have  to  separate  the 
names  with  something  more  obvious, 
such  as  commas.  Additionally,  you  may 
have  some  words  that  access  information 
on  the  stack  but  do  not  consume  it. 
(Some  parts  of  the  stack  may  be  read  but 
not  changed.) 

On  a  past  Forth  project  with  three 
programmers  and  a  $250,000  budget,  we 
developed  our  own  stack  comments  to 
fulfill  our  requirements  of  readability  and 
modifiability  of  thecodebyknowledgable 
programmers.  We  wrote  and  published 
our  own  stack  comments,  confident  that 
anyone  reading  our  code  would  be  able 
to  decipher  them.  Our  stack  comments 
took  the  following  form 

:  CALC -RADIATED -POWER 

(  unit  type;  mode  — >  eff  rad 
power  in  dBm) 

The  translation  scheme  was  that 
everything  to  the  left  of  the  semicolon 
was  unchanged,  but  required  as  an  input. 
Things  to  the  right  of  the  semicolon  were 
changing  parts.  As  you  might  expect, 
things  to  the  left  of  the  arrow  were  con¬ 
sumed,  and  things  to  the  right  of  the 
arrow  were  generated.  The  semicolon  was 
always  required,  the  arrow  was  required 
only  when  the  Forth  word  generated  an 
output.  As  with  the  Fig  comments,  items 
are  listed  in  the  order  they  appear  on  the 
stack,  with  the  least  accessible  items  in 
the  left-most  position.  Thus,  things  that- 
are  not  consumed  must  be  placed  on  the 
stack  before  items  that  are  consumed. 
The  Fig  equivalent  of  the  above  stack 
comment,  with  the  understanding  that 
repeated  items  are  unchanged,  would  be 

(  unit_type  mode - unit-type 

eff_rad_power_ in_ dBm  ) 

We  developed  our  scheme,  rather 
than  using  the  Fig  scheme,  because  we 
needed  to  keep  track  of  both  changed 
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and  unchanged  variables  on  he  stack, 
which  the  Fig  scheme  did  not  explicitly 
support.  Both  schemes,  however,  conveyed 
the  fundamental  information  that  inputs 
are  required  and  outputs  are  generated. 
The  disadvantage  was  that  we  had  two 
different  stack  comment  schemes.  Our 
rather  complicated  applications  used  one 
scheme,  and  our  Fig-Forth  kernel  used  a 
different  scheme.  For  our  purposes,  the 
two  different  schemes  worked  fine,  but 
your  purposes  will  dictate  your  choice. 

Yet  another  way  of  commenting 
your  code  keeps  track  of  the  paramenter 
stack,  the  return  stack,  textual  input, 
memory,  and  whatever  else.  In  this 
scheme,  each  of  these  data  sources/sinks 
has  its  own  comment  line,  with  a  prefix 
on  each  line  indicating  to  what  the  com¬ 
ment  applies.  For  example,  you  might 
see 

( PS  disk  drive - ) 

(  KB  file  name - ) 

( M  buffers - buffers  ) 

This  notation  would  indicate  that  the 
parameter  stack  input  was  a  disk  drive 
number,  that  the  required  keyboard  input 
would  be  a  file  name,  and  that  the  disk 
buffers  would  be  modified. 

As  a  final  embellishment,  each  com¬ 
mented  item  could  include  an  identifier 
relating  to  the  format  of  the  data.  Using 
the  example  above,  but  with  i  standing 
for  integer  and  b  standing  for  byte, 

:  CALC_RADIATED_POWER 

(  b  unit  type;  b  mode  — > 
i  eff  rad  power  ) 

This  gives  really  complete  information 
about  inputs  and  outputs,  but  may  be 
complicated  to  decipher  if  you  have  your 
own  data  types. 

The  whole  purpose  of  stack  com¬ 
ments  is  to  communicate  the  inputs  and 
outputs  of  your  Forth  words.  For  your 
applications  and  your  code  readers,  there 
will  be  good  ways  and  bad  ways  of  com¬ 
municating.  Forth  does  not  force  you 
into  any  set  pattern,  making  you  responsi¬ 
ble  for  choosing  your  own  methodology. 

Other  Forth  source  code  comments 
are  typically  three  types:  what  you  are 
doing,  how  you  are  doing  it,  and  what  is 
on  the  stack  at  the  end  of  each  line.  Most 
of  the  time,  the  name  of  the  Forth  word 
tells  what  you  are  doing.  In  idealized, 
hypothetical  Forth  programming,  you 
never  have  to  give  a  comment  concerning 
how  you  are  doing  this  function  because 
you  connect  the  words  in  your  comment 
with  underbars  of  dashes  and  your  com¬ 
ment  becomes  an  executable  Forth  word. 
This  is  high-level  coding  at  its  best,  as 
exemplified  by  INITIALIZE_SCREEN 
above.  The  price  of  this,  however,  is  that 
you  may  have  a  lot  of  Forth  words  that 
are  only  called  once. 

At  some  point  you  will  not  be  using 
high-level  words,  but  will  have  to  revert 
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to  the  low-level  Forth  kernel  words. 
(This  is  the  same  phenomenon  which 
dictates  that,  when  writing  a  Forth  kernel, 
there  comes  a  point  at  which  you  have  to 
revert  to  the  underlying  assembly  code 
of  the  machine.)  When  you  get  to  this 
lower  level,  chances  are  that  there  will  be 
a  fair  amount  of  stack  manipulation. 
Typically,  30%  of  your  code  will  be  stack 
manipulation  words,  such  as  SWAP, 
DROP,  DUP,  and  the  rest.  Here  it  may  be 
appropriate  to  put  a  comment  at  the  end 
of  each  line  so  that  you  can  keep  track  of 
what  is  on  the  stack,  particularly  in  long 
or  tedious  calculations. 

Spacing  Forth  Words  on  a  Line 

A  good  rule  of  thumb  in  spacing 
Forth  words  on  a  line  is  to  group  the 
words  into  sub -phrases,  phrases,  and 
longer  groups,  just  as  English  is  punctu¬ 
ated  in  phrases  and  clauses.  Most  Forth 
people  agree  that  closely  related  words 
should  be  separated  with  single  spaces 
into  short  sub -phrases,  and  these  sub- 
phrases  should  be  separated  by  multiple 
spaces.  Consider  the  example  in  Figure  1 
(page  100). 

In  the  definition  of  ABC,  notice  that 
the  ARRAY-SIZE  and  the  2-  are  clustered 
into  one  sub-phrase.  In  the  definition  of 
DOUBLE_THE_ARRAY,  again  note  the 
obvious  phrasing.  None  of  this  is  subtle 
or  difficult,  but  it  does  make  things  more 
readable  than  an  equivalent: 

:  2*IT  0  DO  DUP  I  +  DUP @  DUP 
+  SWAP ! 2  +LOOP DROP ; 

To  really  clean  this  up,  you  could  type 
the  code  as  shown  in  Figure  2  (page  100). 
Although  this  simple  example  really  does 
not  need  all  of  these  comments,  the  time 
spent  typing  them  in  is  minimal.  The  real 
effort  of  Forth  programming  is  figuring 
out  what  you  want  to  do  and  how  to  do 
it,  much  of  software  development  time  is 
figuring  out  what  you  actually  did.  A 
short  time  spent  typing  can  preserve  a  lot 
of  thinking  and  figuring. 

Finally,  consider  control  constructs, 
such  as  IF  ELSE  THEN  and  DO  LOOP. 
Most  people  consider  it  good  practice 
that  any  control  construct  which  begins  a 
block  of  code  starts  a  new  line.  The  block 
of  code  underneath  is  usually  indented. 
DOUBLE_THE_ ARRAY  above  shows  a 
DO  phrase  starting  a  line,  and  the  block 
of  code  underneath  it  is  indented.  In 
addition  to  the  layout  of  words  on  a  line, 
it  is  important  to  clearly  structure  your 
code  across  lines.  It  seems  obvious  that 
each  short  sub-phrase  should  be  intact 
on  a  line.  It  is  also  traditional  to  indent 
to  show  the  blocks  which  together  make 
up  a  word,  as  shown  in  Figure  3  (page  101). 
Although  many  people  will  argue  whether 
a  THEN  should  be  at  the  end  of  a  line  or 


at  the  beginning  of  a  new  line,  or  whether 
DO  should  start  a  line,  there  is  agreement 
that  the  underlying  block  structure  of  a 
Forth  word  should  be  reflected  in  the  lay¬ 
out  of  the  code  on  the  screen. 

Miscellaneous  Remarks 

There  are  other  forms  of  coding  stan¬ 
dards  that  you  can  use  in  your  system. 
For  example,  on  the  large  project  men¬ 
tioned  above,  we  had  a  standard  that  all 
words  ending  with  a  question  mark  had 
to  leave  a  true/false  flag  on  the  stack. 
This  gave  us  more  readable  code,  such  as 

IS_THIS_REALLY_THE_CASE? 

IF  DO_SOMETHING_ABOUT_IT 

ELSE  DO_NOTHING  THEN 
THEN 

Another  useful  idea  was  that  all  of 
our  words  which  began  with  GET—  would 
add  to  the  stack.  This  was  a  tremendous 
simplification.  A  final  technique  we 
employed  was  to  separate  our  high-level 
code  and  low-level  code.  High-level  code 
was  comprised  of  user- defined  words 
and  Forth  control  constructs.  Low-level 
words  were  Forth  kernel  words  and  user- 
defined  memory  constructs  such  as  vari¬ 
ables,  constants,  and  arrays.  Our  goal  was 
for  all  of  our  user  words  to  be  either  high 
level  or  low  level,  but  not  to  incorporate 
elements  of  both  high  and  low  level  into 
the  same  word.  This  meant  that  we  could 
show  our  non-software  bosses  our  high- 
level  code,  with  no  comments,  and  they 
could  understand  it.  The  low-level  code, 
with  all  the  stack  comments,  we  kept  to 
ourselves.  Our  success  was  demonstrated 
by  our  ability  to  debug  each  other’s  code 
without  having  seen  it  before  and  having 
no  supporting  documentation,  and  by  the 
number  of  times  major  modifications  to 
different  modules  worked  together  on 
first  integration. 


Conclusion 

Forth  provides  great  powers  to  the 
programmer  to  command  the  computer, 
but  these  powers  do  not  guarantee  easy 
communication  from  programmer  to 
another  human  being.  By  adhering  to  a 
coding  standard,  you  can  ensure  that  your 
code  contains  information  that  other 
people  (not  machines)  need  to  see  in 
order  to  more  easily  understand  your 
code.  In  Forth,  this  information  must 
include:  stack  comments  to  specify 
inputs  and  outputs  to  each  word;  appro¬ 
priate  names  for  words  to  convey  the 
organization  and  function  of  your  code; 
and  appropriate  layout  of  source  code  on 
the  page.  The  variety  of  purposes  of  the 
applications  and  the  programmers,  plus 
human  nature,  will  conspire  to  insure 
that  no  one  format  will  be  universally 
accepted,  but  common  sense  will  dictate 
a  minimum  amount  of  information  that 
must  always  be  included. 
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20  CONSTANT  ARRAY-SIZE 

VARIABLE  ABC  ARRAY-SIZE  2-  ALLOT  (  20  BYTES  TOTAL  RESERVED  ) 

:  DOUBLE_THE_ARRAY  (  ; ARRAY  ADDRESS,  ARRAY  SIZE  IN  BYTES  ) 

0  DO  DUP  I  +  DUP  @  DUP  +  SWAP  !  2  +L00P  DROP  ; 


Figure  1. 


:  DOUBLE  THE  ARRAY 

(  ;array  address,  address  size  in  bytes  ) 

0  DO 

DUP  I  + 

(  ,-array  address,  address  of  Ith  element  ) 

DUP  @  DUP  + 

(  (array  addr,  Ith  addr,  2*  Ith  element  ) 

SWAP  !  2  +  LOOP 

DROP  ,• 

- 

Figure  2. 

:  UNDO  (  ;  ) 

UNDOABLE? 

IF  COMPILING? 

IF  EXECUTING? 

IF  UNDO— IN-DEF&DO 
ELSE  UNDO- IN-DEFINE  THEN 
ELSE  EXECUTING? 

IF  UNDO-EXECUTE  NOTUNDOABLE  THEN  THEN 
ELSE  CANTUNDO  THEN  ( 

DECIMAL  EXIT 


Figure  3. 
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The  rapid  sorting  of  data  is  probably 
one  of  the  most  useful  and  most 
used  capabilities  of  computers,  while 
at  the  same  time  being  one  of  the  least 
understood.  There  are  astonishing  differ¬ 
ences  in  the  performance  obtained  with 
various  sorting  algorithms  under  different 
conditions,  and  to  optimize  sorting  effi¬ 
ciency  requires  knowledge  of  how  certain 
factors  interact  in  any  given  sorting  en¬ 
vironment. 

As  an  aid  to  the  understanding  of 
computer  sorting,  this  article  will  first 
explain  three  relatively  simple  algorithms, 
and  then,  on  the  theory  that  “one  picture 
is  worth  a  thousand  words,”  will  present 
a  user  friendly  sorting  demonstration 
program,  which  graphically  illustrates  dif¬ 
ferences  in  performance.  The  program  is 
coded  in  Forth  because  its  inherently 
structured  form  helps  with  visualizing  and 
understanding  the  action  of  the  sorting 
algorithms. 

The  first  and  simplest  of  the  algo¬ 
rithms  to  be  examined  is  the  well  known 
Bubblesort.  This  algorithm  starts  by  com¬ 
paring  the  second  item  with  the  first  item 
in  the  list  to  be  sorted.  If  they  are  not 
in  correct  relative  order,  it  swaps  them.  It 
then  goes  on  to  compare  the  third  item 
to  the  first,  then  the  fourth  to  the  first 
and  so  on,  until  all  items  have  been  com¬ 
pared  to  the  first  and  swapped  as  re¬ 
quired.  When  this  initial  sequence  is  com¬ 
plete,  the  first  item  in  the  list,  and  only 
the  first,  is  guaranteed  to  be  in  the  correct 
position. 

Bubblesort  then  continues  with  an¬ 
other  sequence  in  which  all  items  further 
down  the  list  are  compared  to  the  second 
item,  swapping  as  necessary.  When  this 
sequence  is  complete,  the  first  two  items 
in  the  list  will  be  in  correct  order.  The 
process  continues  for  number  of  items  in 
the  list  minus  one  sequences  (n-1)  of 
advancing  one  item  and  comparing  all 
items  further  down  the  list  to  it.  As  can 
be  seen,  each  sequence  involves  making 
one  less  comparison  than  the  previous 
sequence,  and  the  final  sequence  involves 
only  the  last  two  items.  At  this  time  the 
whole  list  is  in  order  and  the  process 
ends. 
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Bubblesort  has  the  distinction  of  hav¬ 
ing  the  lowest  performance  rating  of  the 
three  algorithms  being  examined,  because 
it  must  always  perform  n-1  of  the  above 
described  sequences  and,  for  each  se¬ 
quence,  must  always  compare  the  selected 
item  with  all  of  the  remaining  items  in 
the  list.  Thus  when  the  number  of  items 
to  sort  is  doubled,  the  sorting  process 
takes  approximately  four  times  longer, 
reaching  unacceptable  limits  very  quickly. 

The  second  algorithm  to  be  examined 
is  the  less  well  known  Shuttlesort,  which 
is  in  the  same  efficiency  class  as  Bubble- 
sort  but  which  has  a  refinement  that 
provides  a  surprising  performance  differ¬ 
ence.  Shuttlesort  begins  by  comparing  the 
second  item  to  the  first,  swapping  them  if 
necessary.  It  then  proceeds  to  compare 
the  third  item  to  the  second,  then  the 
fourth  to  the  third  and  so  on,  until  it 
reaches  the  end  of  the  list. 

When  a  pair  of  items  being  compared 
are  in  the  wrong  order,  they  are  swapped 
and  Shuttlesort  backs  up  to  compare  the 
item  just  swapped  with  the  previous  item 
in  the  list,  swapping  again  if  necessary. 
The  backing  up  process  continues  until  a 
pair  in  the  correct  order  is  found,  at 
which  time  Shuttlesort  jumps  forward  to 
a  point  one  item  ahead  of  where  the 
backing  up  started  and  continues  where 
it  left  off. 

The  described  action  causes  out  of 
order  items  to  “shuttle,”  one  at  a  time, 
from  their  initial  position  to  their  final 
position,  and  is  also  the  basis  for  the 
above  mentioned  surprise  performance. 
If  Shuttlesort  is  run  on  an  already  - 
ordered  list,  it  will  take  less  time  to  com¬ 
plete  its  task  than  any  other  algorithm 
in  existence,  regardless  of  the  size  of  the 
list.  It  is  also  quite  fast  on  nearly  ordered 
lists. 

The  final  algorithm  to  be  examined 
is  the  Shell-Metzner  Sort,  or  Shellsort  as 
it  is  commonly  called.  Shellsort  is  basi¬ 
cally  the  Shuttlesort  algorithm,  with  a 
small,  but  all  important,  additional  fea¬ 
ture  that  increases  its  efficiency  con¬ 
siderably.  With  Shellsort,  doubling  the 
number  of  items  to  be  sorted  results  in 
only  a  2.3  to  2.4  fold  increase  in  sort  time, 
providing  an  excellent  tradeoff  between 
algorithm  complexity  and  efficiency. 

The  Shellsort  algorithm  first  sets  an 
initial  distance,  which  is  something  more 
than  half  the  total  number  of  items  in 
the  list  to  be  sorted.  It  then  compares 
items  in  the  list,  separated  from  each 


other  by  this  initial  distance,  using  the 
Shuttlesort  method  of  stepping  down  the 
list  making  comparisons  and  swaps.  When 
it  completes  the  list  using  the  initial  dis¬ 
tance,  it  decreases  the  distance  by  half 
and  runs  down  the  list  again.  The  process 
of  decreasing  the  distance  by  half  and 
making  a  Shuttlesort  pass  down  the  list 
continues  until  the  final  pass  is  made 
using  a  distance  of  one. 

This  final  pass  is  identical  to  a 
Shuttlesort,  but  is  very  fast,  since  the 
previous  passes  have  left  the  list  in  near 
sorted  order.  Shellsort  owes  its  speed  and 
efficiency  to  the  fact  that  because  it  can 
move  out  of  place  items  over  initially 
large,  and  then  successively  finer  dis¬ 
tances,  it  makes  fewer  comparisons  and 
swaps  than  the  other  algorithms  discussed. 
If  run  on  an  already  ordered  list,  however, 
it  does  not  show  as  dramatic  a  decrease  in 
run  time  as  Shuttlesort,  because  it  must 
make  a  separate  pass  for  each  distance. 

The  demonstration  program  will  pro¬ 
vide  an  interesting  side-by-side  compari¬ 
son  of  the  three  sorting  algorithms  dis¬ 
cussed,  under  three  different  conditions. 
The  first  sort  is  made  on  randomly 
ordered  data,  which  represents  an  ap¬ 
proximation  of  a  typical  sorting  situation. 
Next  the  same  algorithm  is  run  a  second 
time  on  the  sorted  data,  to  observe  the 
algorithm’s  sensitivity  to  the  data  order 
by  contrasting  best  case  conditions.  Fi¬ 
nally,  the  algorithm  is  run  again  on  data 
in  reversed  chronological  order,  to  observe 
the  algorithm’s  sensitivity  to  worst  case 
conditions. 

The  demonstration  program  (written 
in  Fig-Forth  79  2.1)  is  straightforward 
and  should  run  on  all  dialects  of  Forth 
with  only  small  changes.  The  following 
comments  will  help  resolve  any  system 
differences: 

1.  Fig-Forth  users  should  change  NE¬ 
GATE  in  SHELLSORT  to  MINUS. 

2.  79  Standard  Forth  users  should  change 
the  -2  loop  limit  for  the  inner  DO 
loop  of  both  SHUTTLESORT  and 
SHELLSORT  to  0. 

3.  BEEP  is  defined  as  07  EMIT. 

4.  PAGE  is  defined  as  0C  EMIT. 

5.  The  CONSTANT  ARRAY1  defines  the 
starting  address  for  the  array  to  be 
sorted.  The  array  address  was  allocated 
directly,  in  order  to  allow  arbitrarily 
large  arrays  to  be  created,  without  hav¬ 
ing  to  ALLOT  a  large  block  of  Forth’s 
dictionary  space  and  to  demonstrate 
the  flexibility  of  Forth.  Those  users 
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who  do  not  have  sufficient  room  out¬ 
side  of  Forth’s  program  space  or  who 
are  uncomfortable  with  this  method 
may  use  the  more  traditional  procedure 
of: 

1.  CREATE ARRAY1 XXX  ALLOT  - 
for  79  Standard. 

2.  0  VARIABLE  ARRAY1  XXX-2 
ALLOT  —  for  Fig  Forth. 
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The  Forth  Sort  (Text  begins  on  page  102) 


SCR  #  21 

0  <  1 6  b  .i  t.  N u in e r  leal  S ort  Demo  2 0 A IJ G 8 2 M 1 M ) 

1 

2  FORTH  DEFINITIONS  HEX 

3  CREATE  ARRAY  1  402  ALLOT  (  address  of  data  array) 

4  VARIABLE  #ELEMENTS  (  number  of  16  bit  elements) 

5  VARIABLE  DISTANCE  (  distance  between  elements) 

6  VARIABLE  VI  <  temporary  indexes  for  nested  "D0"s) 

7  VARIABLE  VJ 

8  VARIABLE  SEED  HERE  SEED  ! 

9 

10  s  RND  (  random  #  generator)  (  n  -  ) 

11  SEED  ®  103  *  3  +  7FFF  AND 

12  DUP  SEED  !  7FFF  */  ; 

13  :  CL.RS  PAGE  CR  CR  17  SPACES  .  "  FORTH  SORTING  DEMO"  CR  ; 

14  s  KEYMSG  .  "  any  key  continues.."  CR  KEY  DROP  ; 

15 


SCR 

0 

1 


4 

5 
h 
7 

a 

9 
10 
i  i 
12 

13 

14 


#  22 

(  16  bit  Numerical  Sort  Demo  20AUGS2M I'M ) 


;  RANDOM  (  create  random  pattern  in  ARRAY  1 ) 

#ELEMENTS  S)  2*  0  (  set  loop  limit  and  initial  index) 

DO  3E8  RND  (  fetch  random  #  between  0  and  999) 

1  3  MOD  0=  IF  NEGATE  <  negate  1  out  of  three) 

THEN  I  ARRAY1  +  !  (  store  in  array) 

2  -fLOOP  ;  <  increment  loop) 

(  create  reversed  pattern  in  ARRAY1) 
(  set  loop  limit  and  initial  index) 
I  —  (  compute  value) 

+  !  <  store  in  array) 

(  decrement  loop) 


:  REVERSE 

(♦ELEMENTS  ®  0 

DO  ((ELEMENTS  5) 
I  2*  ARRAY 1 
LOOP  ; 


(Continued  on  page  106 ) 
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Forth  Sort  (Listing  continued,  text  begins  on  page  102) 


SCR 

# 

x..  •_.* 

0 

1 

< 

16  bit  Numerical  Sort  Demo 

20AUG82MIM) 

4. 

2 

NUM  < I )  3  ARRAY 1  +  ; 

( 

array  fetch) 

T* 

NUM I 3  NUM (I)  3  ; 

< 

and  store) 

4 

NUM I !  NUM ( I )  !  ; 

( 

operators) 

vJ 

6 

2 

COMPARE  VI  NUM I 3  VJ  NUM I 3  >  ; 

(  true  if  #1 

>  ttJ) 

7 

8  :  NUMSWAP  (  swap  elements  of  array)  (  -  ) 

9  V I  NUM 1 3  V J  NUM IS)  VI  NUM I  !  V J  NUM I  !  ; 

10 

11  :  NUMLIST  <  output  number  array)  (  -  ) 

12  ttELEMENTS  32*  0  DO  I  DUP 

13  1A  MOD  0=  IF  CR  THEN  ARRAY  1  +  3 

14  6  .  R  2  +L.Q0P  CR  CR  ; 

15 


SCR  #  24 

0  <  16  bit  Numerical  Sort  Demo  20AUG82MIM) 

1 

2  :  BUBBLESORT  (  sort  data  array)  (  -  ) 

3  #ELEMENTS  3  1-  2*  0  DO  I  VI  ! 

4  ttELEMENTS  3  2*  I  2+  DO  I  VJ  ! 

5  COMPARE  IF  NUMSWAP 

6  THEN  2  +L.00P  2  +L00P  ; 

7 

8  :  SHUTTLESORT  (  sort  data  array)  (  -  ) 

9  #ELEMENTS  3  1-  2*  0  DO 

10  -2  I  DO  I  DUP  VI  !  2+  VJ  ! 

11  COMPARE  IF  NUMSWAP  ELSE  LEAVE 

12  THEN  -2  +L00P  2  +L00P  $ 

14  (  For  decending  sorts  change  >  in  COMPARE"  to  <> 

15 


0  (  16  bit  Numerical  Sort  Demo  20AUG82MIM) 

1 

2  :  SETDIST  (  set  initial  distance)  (  -  ) 

3  1  BEGIN  2*  DUP  ttELEMENTS  3  > 

4  UNTIL  2-  DISTANCE  !  ; 


6  :  DECDIST  (  decrement  distance)  (  -  flag) 

7  DISTANCE  3  2/  2/  2*  DUP  DISTANCE  !  2  <  ; 

8 

9  (  Shel 1  — Metsner  sort) 

10  :  SHELLSORT  SETDIST  BEGIN  <  sort  data  array)  (  -  ) 

11  ttELEMENTS  3  2*  DISTANCE  3  -  0  DO  -2  I  DO 


106 

544 


Dr.  Dobb’s  Journal,  Number  83,  September  1983 


12  I  DUP  VI  !  DISTANCE  5)  +  VJ  !  COMPARE  IF 

13  NUMSWAP  ELSE  LEAVE  THEN  DISTANCE  3  NEGATE 

14  +LOOP  2  +LOOP  DECDIST  UNTIL  ; 

15 


SCR  #  26 

0  (  16  bit  Numerical  Sort  Demo  20AUG82MIM) 

1  (  benchmark  it) 

2  :  #ELEMENTS?  CR  . "  How  many  elements?  "  QUERY  CR  CR 

3  INTERPRET  #ELEMENTS  !  . "  random  array"  RANDOM  NUMLIST  ; 

4  :  REV IT  CR  . "  reversed  array"  REVERSE  NUMLIST  ; 

5 

6  :  BUBBS  #ELEMENTS?  ."  random  bubblesort ..  ,r  CR  BEEP 

7  BUBBLESORT  BEEP  NUMLIST  KEYMSG  .  "  sorting  sorted  array..." 

8  CR  BEEP  BUBBLESORT  BEEP  KEYMSG  REV IT 

9  . "  reverse  bubblesort . . "  CR  BEEP  BUBBLESORT  BEEP 

10  NUMLIST  KEYMSG  ; 

11  :  SHUTS  #ELEMENTS?  random  shutt.  I  esort .  .  "  CR  BEEP 

12  SHUTTLESORT  BEEP  NUMLIST  KEYMSG  .  "  sorting  sorted  array.." 

13  CR  BEEP  SHUTTLESORT  BEEP  KEYMSG  REV IT 

14  ."  reverse  shutt 1 esort "  CR  BEEP  SHUTTLESORT  BEEP 

15  NUMLIST  KEYMSG  ; 


SCR  #  27 

0  (  16  bit  Numerical  Sort  Demo  20AUG82MIM) 

1 

2  :  SHEL.S  #ELEMENTS?  ."  random  shell  sort.."  CR  BEEP 

3  SHELLSORT  BEEP  NUMLIST  KEYMSG  sorting  sorted  array.." 

4  CR  BEEP  SHELLSORT  BEEP  KEYMSG  REV IT 

5  ."  reverse  shell  sort.."  BEEiP  SHELLSORT  BEEP 

6  NUMLIST  KEYMSG  ; 

7  :  DECODE  DUP  31  =  IF  BUBBS  ELSE  DUP  32  =  IF  SHUTS  ELSE 

8  DUP  33  =  IF  SHEL.S  ELSE  34  -  IF  QUIT  THEN  THEN  THEN  THEN  ; 

9  :  MENU  CR  CR  ."  Specify  sort  algorithm:"  CR 

10  . "  1  -  Bubblesort"  CR  . "  2  -  Shutt 1 esort "  CR 

11  ."  3  -  Shell  sort"  CR  . "  4  -  Exit  demo  "  BEGIN 

12  KEY  DUP  30  >  OVER  35  <  AND  NOT  WHILE  DROP  REPEAT  ; 

13 

14  :  DEMO  BEGIN  CLRS  MENU  DUP  DECODE  AGAIN  ; 

1 5  DEC  I MAL. 


End  Listing 
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CP/M  EXCHANGE 


by  Robert  Blum 


Some  of  the  most  sensitive  and  dif¬ 
ficult  to  understand  parts  of  BIOS  code 
are  the  sections  dealing  with  disk  control. 
Reviewing  what  must  be  accomplished 
and  the  associated  problems  is  prerequisite 
to  digging  in  and  making  changes.  Since 
it  seems  that  writing  a  new  BIOS  for 
CP/M  Plus  is  practically  mandatory,  a 
brief  review  of  disk  controllers  and  re¬ 
cording  methods  is  in  order. 


FM  and  MFM  Recording 

When  recording  data  on  magnetic 
media  the  single  most  limiting  factor  to 
how  much  data  can  be  stored  is  the 
media  itself.  To  record  one  bit  of  data 
requires  that  some  magnetic  indication  be 
given  that  a  state  change  has  taken  place. 
In  its  simplest  form  this  change  is  a  flux 
reversal.  This  can  be  viewed  as  driving 
along  a  newly  paved  road.  It  feels  per¬ 
fectly  smooth  to  you  only  because  the 
suspension  system  of  your  car  has  been 
designed  to  filter  out  any  minor  irregular¬ 
ities  in  the  road’s  surface.  But  when  com¬ 
ing  to  an  intersection  guarded  by  speed 
strips  the  suspension  system’s  ability  to 
filter  out  bumps  is  exceeded,  making  you 
aware  that  something  has  changed.  Mag¬ 
netic  media  also  has  a  background  or 
residual  noise  level  present.  It  is  of  little 
consequence  because  it  is  filtered  out 
electronically.  As  the  speed  strip  got  your 
attention  so  does  a  data  bit  as  it  passes 
under  the  read/write  head  of  your  floppy 
disk  drive.  Its  presence  is  known  by  a 
voltage  potential  well  above  the  normal 
background  noise  level. 

When  designing  a  magnetic  recording 
and  recovery  system,  a  great  number  of 
trade-offs  must  be  made.  A  suitable  cost/ 
performance  ratio  for  small  computers  is 
met  by  maintaining  relatively  low  record¬ 
ing  densities  that  allow  lower  priced  media 
and  fairly  large  mechanical  variances  to 
still  give  acceptable  levels  of  performance. 

For  example,  let’s  assume  that  one 
bit  cell  time  (the  minimum  amount  of 
time  necessary  to  safely  achieve  one  flux 
reversal)  is  2  microseconds  (millionths  of 
a  second)  on  a  disk  rotating  at  360  revo¬ 
lutions  per  minute  (RPM).  A  quick  calcu¬ 
lation  reveals  that  over  83  thousand  bits 
can  be  recorded  in  a  single  revolution  of 
the  disk.  Unfortunately,  not  all  of  this 
recording  area  can  be  used  for  data  stor¬ 
age.  Some  of  it  is  used  for  overhead 
functions  such  as  identifying  sectors  and 
storing  the  checksums  used  for  data  veri¬ 
fication  on  read-back. 
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Frequency  Modulation  (FM),  also 
known  as  single-density  recording,  was 
the  first  to  emerge  and  still  retains  its 
position  as  the  standard  interchange  for¬ 
mat  for  8 -inch  disk  drives.  Because  of  its 
low  recording  density  it  is  seldom  used 
today  with  5-inch  drives.  For  example, 
my  first  disk  system  was  a  North  Star 
MDS  that  used  Shugart  SA400  5 -inch, 
single-sided,  single -density  drives.  Maxi¬ 
mum  storage  capacity  of  each  disk  was 
limited  to  only  90K  bytes.  At  that  time 
nothing  else  was  available  that  provided 
more  storage,  that  would  also  fit  into 
my  budget,  so  a  great  deal  of  disk  swap¬ 
ping  went  on. 

FM  recording,  Figure  1  (page  112), 
offers  the  lowest  recording  density  be¬ 
cause  each  data  bit  is  encoded  with  one 
clock  bit.  Very  reliable  data  retrieval, 
even  within  a  wide  mechanical  tolerance 
specification,  is  insured  by  using  this 
method;  however,  total  data  capacity 
suffers. 

To  achieve  greater  storage  capacity 
without  significantly  increasing  hardware 
and  media  costs  was  the  mother  of  inven¬ 
tion  to  Modified  Frequency  Modulation 
(MFM)  recording,  Figure  2  (page  112). This 
method  does  not  require  accompanying 
each  data  bit  with  a  clock  bit.  Clock  bits 
are  only  inserted  when  two  consecutive 
bit  cells  contain  zero  data  bits.  This 
insures  that  the  longest  delay  between 
any  two  flux  reversals  will  be  one  bit  cell 
time.  When  MFM  was  first  introduced  it 
was  met  with  a  great  deal  of  skepticism. 
At  that  time  many  computer  manufac¬ 
turers  made  their  thoughts  perfectly  clear: 
double  density  would  at  best  be  barely 
capable  of  maintaining  the  excellent  error 
rates  of  FM  recording.  Fortunately  for 
us,  the  design  engineers  knew  better  and 
continued  to  refine  read/write  heads  and 
their  controlling  electronics.  Today  double 
density  is  the  standard  recording  method. 

Making  It  Go  Click  .  .  .  Whir 

My  disk  controller  board  is  built 
around  the  very  popular  Western  Digital 
1793  that  is  used  in  many  of  today’s 
computer  systems.  The  WD1793  is  only 
one  in  a  large  family  of  disk  controller 
chips  that  evolved  several  years  ago  to 
meet  the  demand  for  floppy  disk  based 
systems.  Prior  to  their  introduction  most 
disk  controller  subsystems  were  built 
from  TTL  parts.  This  required  that  a  large 
portion  of  PC  board  real  estate  be  devoted 
to  just  this  one  function.  In  a  bus- 
oriented  system,  such  as  the  S-100,  space 


isn’t  a  major  problem  because  plenty  of 
extra  slots  are  generally  available.  How¬ 
ever,  as  desktop  computers  became  more 
popular,  devoting  a  large  amount  of  PC 
board  space  to  just  one  function  came 
under  close  scrutiny  of  the  design  engi¬ 
neers.  Additionally,  heat  dissipation  and 
cost  were  also  factors  that  demanded  a 
more  compact  approach  to  controlling 
floppy  disks. 

Western  Digital’s  first  single -chip  con¬ 
troller  that  gained  widespread  acceptance 
was  the  1771.  It  was  designed  to  control 
either  5-  or  8 -inch  single-density  single¬ 
sided  disk  drives.  As  disk  drive  manufac¬ 
turers  responded  to  the  need  for  more 
storage  by  introducing  drives  with  dual 
heads  and  double -density  recording  capa¬ 
bilities  WD  introduced  the  179X  series. 
To  build  a  complete  disk  controller  using 
one  of  these  chips  only  requires  a  small 
amount  of  external  logic  to  handle  data 
separation  and  bus  control.  Further  re¬ 
ductions  in  the  amount  of  supporting 
logic  has  been  brought  about  by  WD’s 
recent  announcement  of  the  WD279X 
series  that  incorporates  the  data  separator 
logic  on  chip. 

Contained  on  each  of  these  single 
chip  controllers  is  a  complete  logic  sub¬ 
system  rivaling  the  power  of  most  8 -bit 
cpus  in  use  today.  After  receiving  a  few 
parameters  and  a  single  command  they 
will  independently  perform  all  the  func¬ 
tions  necessary  to  properly  position  the 
drive  R/W  heads  and  transfer  the  desired 
data  sector  to  or  from  the  recording 
media.  For  example,  to  read  a  sector 
requires  only  four  software  steps.  First, 
load  the  track  register  with  the  target 
track  number.  Second,  place  the  desired 
sector  number  into  the  sector  register. 
Third,  load  the  command  register  with  a 
SEEK  operation  code.  Upon  receipt  of 
the  SEEK  command  the  controller  chip 
automatically  steps  to  the  desired  track 
and  verifies  the  final  head  position  by 
reading  the  first  sector  id  that  comes 
along.  If  the  disk  heads  were  not  loaded 
at  initiation  of  the  seek  they  are  inserted 
with  the  appropriate  head  settle  delay  to 
insure  reliable  operation.  Providing  no 
error  is  found  during  the  seek  operation 
we  are  ready  for  the  final  step.  Finally, 
load  the  command  register  with  a  READ 
command.  This  sets  the  controller  chip 
into  scan  mode  which  reads  each  sector 
id  until  one  is  found  that  matches  the 
value  placed  into  the  sector  register  during 
setup.  The  data  portion  of  the  sector  is 
now  transferred  and  the  data  content 
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CRC  is  checked  to  verify  that  the  read 
operation  was  successful.  Obviously,  this 
is  a  simplified  description  of  a  compli¬ 
cated  task  performed  by  the  controller 
chip,  but  from  a  software  viewpoint  little 
else  is  required. 

If  you  want  to  know  more  about  any 
of  Western  Digital’s  controller  chips  you 
can  contact  them  directly  at:  Technical 
Publications,  Western  Digital  Corporation, 
3128  Redhill  Avenue,  Box  2180,  New¬ 
port  Beach,  California  92663.  They  have 
a  number  of  technical  data  sheets  and 
application  notes  available  at  reasonable 
cost. 

Catch  That  Error 

Preparing  to  write  a  new  BIOS  for 
CP/M  Plus  has  been  very  revealing  of  my 
hidden  work  habits.  Soon  after  starting 
review  of  my  current  BIOS  I  was  struck 
by  a  flood  of  “Things  To  Do”  that  I  had 
never  completed.  Most  of  them  were  con¬ 
venience  items,  such  as  allowing  a  drive 
not  ready  condition  to  be  cleared  with  a 
control-C  and  adding  improved  I/O  re¬ 
direction  capabilities.  But  some  others 
could  not  possibly  be  dismissed  as  wish 
list  items. 

One  problem  that  I  face  daily  is 
using  a  disk  system  that  is  beginning  to 
show  its  age.  Far  too  many  hours  of  con¬ 
stant  use  without  any  preventive  main¬ 
tenance  has  taken  its  toll.  This  fact  in 
conjunction  with  the  rather  unsophisti¬ 
cated  error  recovery  routines  of  my  BIOS 
causes  me  consternation  each  time  I  start 
a  backup  of  my  not  easily  replaced  disk 
files.  This  is  particularly  true  when  I 
attempt  to  copy  a  complete  disk.  I  say 


attempt  with  no  pun  intended.  More 
often  than  not  I  encounter  at  least  one 
file  that  will  not  verify  properly  because 
of  a  read  or  write  error.  Usually  it  will 
copy  successfully  on  the  second  or  third 
attempt;  however,  I  have  been  greeted 
with  disaster  several  times  when  multiple 
recovery  attempts  failed  and  I  had  to 
recreate  the  file  from  scratch.  Determin¬ 
ing  exactly  what  is  causing  the  problem 
on  my  system  is  not  nearly  as  simple  as 
it  could  be.  I  use  boards  from  a  number 
of  different  manufacturers.  All  are  plugged 
into  a  motherboard  that  was  never  de¬ 
signed  to  handle  the  bandwidth  in  use. 
And  the  edge  connectors  have  aged  be¬ 
yond  being  able  to  provide  a  tight  con¬ 
nection.  Obviously,  the  easiest  solution 
to  my  dilemma  would  be  to  upgrade  my 
equipment  and  send  the  disk  drives  out 
for  a  thorough  cleaning  and  recalibration. 
But,  the  buffalo  on  the  nickel  bellowing 
and  my  sheer  fright  at  being  without  a 
computer  for  several  weeks  have  inti¬ 
midated  me  to  the  point  of  waiting  and 
hoping  for  the  best.  I  understand  all  too 
well  that  one  day  soon  I  may  be  faced 
with  a  pile  of  smoking  rubble  that  was 
once  my  beloved  friend  and  companion 
on  many  dark  nights  and  rainy  after¬ 
noons.  But  for  now,  hope  continues  to 
mask  the  stark  realities. 

To  shorten  the  length  of  down  time 
I  have  enhanced  the  error  reporting  logic 
of  my  BIOS  in  hopes  of  being  able  to 
pinpoint  the  problem.  My  original  intent 
was  to  put  in  enough  code  to  clearly 
explain  in  English  that  an  error  had  oc¬ 
curred  and  exactly  what  it  was.  I  also 


wanted  to  keep  track  of  each  error  by 
type  so  that  totals  could  be  displayed  at 
warm  boot  time.  What  I  actually  imple¬ 
mented  leaves  a  lot  to  be  desired  because 
of  the  limited  amount  of  space  remaining 
in  my  BIOS,  but  it  serves  its  purpose.  The 
routine  I  wrote  (Listing  One,  page  114), 
will  display,  in  binary,  the  status  of  the  disk 
controller  after  10  recovery  attempts  have 
failed  to  clear  the  error.  With  this  informa¬ 
tion  it  is  then  a  simple  task  to  find  the 
error  in  the  manufacturer’s  literature. 

TWITTLE 

Sitting  in  front  of  my  CRT  for  several 
minutes  wondering  whether  my  program 
has  gone  south  or  is  just  taking  its  time 
led  me  to  write  a  subroutine  to  visually 
give  some  indication  as  to  what  is  going 
on.  I  didn’t  want  to  slow  a  program’s 
execution  considerably  by  displaying  long 
messages  or  writing  a  lot  of  extra  code  for 
testing  that  would  be  stripped  out  later. 
TWITTLE,  (Listing  Two,  page  116), 
meets  both  of  these  requirements  for  me. 

TWITTLE  displays  an  asterisk  in  the 
current  cursor  position  that  appears  to 
bounce  as  the  program  runs.  Careful  selec¬ 
tion  of  the  points  in  your  program  where 
TWITTLE  is  called  will  give  you  not  only 
visual  indication  that  your  program  is  still 
active  but  its  level  of  activity  as  well. 

TWITTLE  works  by  using  a  one-byte 
save  area  as  a  flip-flop  flag.  On  each 
entry  this  flag  is  tested  to  determine  what 
was  displayed  on  the  last  entry.  In  this 
way  the  subroutine  knows  to  display 
either  an  asterisk  or  a  space  to  turn  the 
asterisk  off.  To  avoid  destroying  any  data 
on  the  CRT  screen  by  outputting  a  long 
string,  a  backspace  is  output  after  each 
indicator  character. 

As  I  said  before,  be  mindful  of  where 
TWITTLE  is  called.  Calling  it  too  often 
will  produce  what  appears  to  be  a  steady 
asterisk  while  not  calling  it  often  enough 
still  has  you  sitting  and  waiting  for  some¬ 
thing  to  happen.  As  a  guide,  I  used 
TWITTLE  in  a  program  that  read  in  a 
disk  file,  selecting  certain  records  and 
then  sorting  them.  I  called  TWITTLE 
before  reading  each  input  record  and  then 
again  as  each  sort  pass  completed.  While 
reading  the  disk  file  the  frequency  of  the 
bouncing  asterisk  indicated  how  many 
records  were  being  selected.  And  as  the 
table  was  being  sorted  a  steady  indication 
assured  me  that  the  program  was  still 
active. 

I  deviated  from  my  charted  course 
over  the  past  couple  of  months  based  on 
your  input.  Next  month  I  plan  to  cover 
BDOS  function  code  31  in  greater  detail 
and  talk  some  more  about  CP/M  Plus’s 
features.  I  also  hope  to  be  able  to  tell  you 
about  a  new  program  that  was  offered 
to  me.  It  looks  like  a  super  instructional 
tool  for  CP/M. 

( Listings  begin  on  page  114) 
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CP/M  Exchange  (Text  begins  on  page  110) 

Listing  One 


DISPLAY  DISK  CONTROLLER  STATUS  IN  BINARY  SUBROUTINE 

THIS  SUBROUTINE  WILL  DISPLAY  THE  1793  DISK  CONTROLLER  CHIP 
STATUS  IN  BINARY 

INPUTS:  A  =  VALUE  TO  BE  DISPLAYED 
OUTPUTS:  NONE 
REGISTERS  USED:  NONE 


DSKST 

EQU 

$ 

PUSH 

PSW 

PUSH 

BC 

PUSH 

DE 

LD 

C ,  CR 

CALL 

CONOUT 

LD 

C  ,  LF 

CALL 

CONOUT 

IN 

A,  ( DSTAT) 

LD 

D ,  A 

LD 

B  ,8 

DSKSTR 

EQU 

$ 

LD 

A ,  D 

RLA 

LD 

D,  A 

LD 

A,'  0' 

ADC 

A ,  0 

LD 

C ,  A 

CALL 

CONOUT 

DJNZ 

DSKSTR 

POP 

DE 

POP 

BC 

POP 

PSW 

RET 

SAVE  USER  REGISTERS 
* 

* 

OUTPUT  CR  AND  LF  BEFORE  DISPLAY 
* 

* 

* 

READ  DISK  STATUS 
SAVE  IN  REGISTER  D 
NUMBER  OF  BITS  TO  DISPLAY 


CURRENT  STATUS  BYTE  TO  REGISTER  A 

HIGH  ORDER  BIT  TO  CARRY 

SAVE  CURRENT  STATUS  BYTE 

ASCII  ZERO  TO  REGISTER  A 

IF  CARRY  SET  ADD  1 

CHARACTER  TO  C  FOR  CONOUT 

ROUTINE 

PUT  CHARACTER  TO  CRT 
LOOP  UNTIL  COMPLETE 

;  RESTORE  USER  REGISTERS 

.  * 

.  * 

; BACK  TO  CALLER 

End  Listing  One 


in 
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TWITTLE  SUBROUTINE 


1  16 


This  subroutine  will  alternately  display  an  asterick  and  space 
at  cursor  position 

INPUTS:  NONE 
OUTPUTS:  NONE 
REGISTERS  USED:  NONE 


NAME  ( 1 TWITLE' ) 
.  Z80 

ENTRY  TWITLE 


i 

f 

EQUATES  FOR 

THIS  ROUTINE 

cos 

EQU 

9 

BDOS 

EQU 

5 

BKSP 

EQU 

8 

SPACE 

EQU 

1  1 

AST 

EQU 

•  *  « 

DOLLAR 

EQU 

ENTRY  POINT 

AND  MAIN  CODING 

TWITLE 

EQU 

$ 

PUSH 

PSW 

PUSH 

BC 

PUSH 

HL 

LD 

A,  ( INDBYT) 

BIT 

7, A 

JR 

Z  ,TWITB 

TWITA 

EQU 

$ 

LD 

DE , TWITIN 

RES 

7, A 

LD 

( INDBYT)  ,  A 

CALL 

PMSG 

TWITEX 

EQU 

$ 

POP 

HL 

POP 

BC 

POP 

PSW 

RET 

PRINT  CONSOLE  STRING  FUNCTION 
BDOS  JUMP  OFF  POINT 
BACKSPACE  CODE 
SPACE  CONSTANT 
ASTERICK  CONSTANT 
DOLLAR  SIGN  CONSTANT 


;  SAVE  ALL  USER  REGISTERS 

.  * 

.  * 

; GET  DIRECTION  BYTE 
; CHECK  DIRECTION  BYTE 


ERASE  ASTERICK  STRING 
RESET  DIRECTION  BYTE 
SAVE  DIRECTION  BYTE 
DISPLAY  MESSAGE  ON  CONSOLE 


; RESTORE  ALL  USER  REGISTERS 

.  * 

.  * 

; BACK  TO  USER 


(Continued  on  page  119) 
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CP/M  Exchange  (Listing  continued,  text  begins  on  page  1 10) 

Listing  Two 


TWITB 

EQU 

$ 

LD 

DE, TWITOT 

SET 

7, A 

LD 

(  INDBYT)  ,  A 

CALL 

PMSG 

JR 

TWITEX 

PMSG 

EQU 

$ 

LD 

C,COS 

CALL 

BDOS 

RET 

1 

r 

9 

CONSTANTS  AND 

SAVE  AREAS 

TWITOT: 

DB 

AST, BKSP, DOLLAR 

TWITIN: 

DB 

SPACE,BKSP, DOLLAR 

INDBYT: 

DB 

0 

END 

DISPLAY  ASTERICK  STRING 
SET  DIRECTION  BYTE 

SAVE  DIRECTION  BYTE 
DISPLAY  MESSAGE  ON  CONSOLE 
EXIT 


PRINT  STRING  FUNCTION  CODE 
ALLOW  BDOS  TO  DISPLAY  ENTIRE 
STRING 

BACK  TO  USER 


End  Listing  Two 
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16-BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


Language  Benchmarks 

An  interesting  program  to  test  the 
speed  and  accuracy  of  various  high-level 
languages  has  been  sent  to  us  by  Bill 
Savage  of  Microfloat  in  Houston,  Texas 
(see  Listing  One,  page  122).  In  the  8 -bit 
versions,  the  CPU  was  an  8085  at  5  MHz. 
The  16-bit  CPU  was  an  8086  at  5  MHz. 
The  floating-point  hardware  versions 
used  the  Intel  8232  (8  bit)  or  the  Intel 
8087  (16  bit).  The  final  result  of  each 
test  should  be  2500.000;  any  variations 
from  this  figure  reflect  errors  in  the  lan¬ 
guage’s  floating-point  algorithms  or  round¬ 
ing  methods.  The  arctangent  in  the  cen¬ 
tral  function  is  designed  to  accentuate 
such  discrepancies  and  make  them  more 
visible.  The  execution  times  are  listed  in 
increasing  order  in  Table  1  (page  122);  the 
accuracy  results  speak  for  themselves. 

Although  all  of  the  results  with  the 
standard  software  foating-point  libraries 
showed  poor  accuracy,  the  PL/I  results 
were  especially  surprising.  This  compiler 
has  always  had  a  reputation  for  high  qual¬ 
ity  and  performance.  Not  only  was  the 
result  farther  off  than  with  any  other 
language,  but  the  code  produced  by  the 
PL/I -86  compiler  was  actually  slower 
than  the  BASIC-86  interpreter!  Another 
interesting  observation  was  the  small 
difference  in  execution  times  on  this  test 
between  compiled  and  interpreted  BASIC, 
demonstrating  that  on  number- crunching 
programs  relatively  little  time  is  being 
spent  in  the  interpreter. 

Optical  Mouse  Interface 

Rick  Wilton  contributed  two  short 
programs  which  demonstrate  use  of  a 
“mouse”  on  the  IBM  PC.  He  used  the 
MSC  M-l  Optical  Mouse  sold  by  Mousf 
Systems  Corp.,  2336H  Walsh  Ave.,  Santa 
Clara,  CA  95051.  The  software  assumes 
that  the  mouse  is  on  the  first  serial  port 
-  COMO. 

A  BASIC  version  of  the  interface  is 
supplied  as  Listing  Two  (page  123),  and  a 
Forth  version  as  Listing  Three  (page  126). 
The  BASIC  version  may  be  used  in  the  or¬ 
dinary  text  display  mode,  while  the  Forth 
program  uses  the  medium-resolution 
graphics  mode.  In  the  latter  version,  push¬ 
ing  the  left  button  causes  the  mouse  to 
leave  a  trail  and  pushing  all  three  buttons 
at  once  ends  the  demonstration. 

The  mouse  sends  out  a  packet  of  five 
data  bytes  whenever  there  is  a  change  of 
mouse  state.  This  change  may  either  be  a 
movement  or  a  switch  transition.  The 
first  byte  of  a  packet  always  has  the  bit 


pattern  lOOOOxxx,  so  the  driver  program 
can  synchronize  with  the  mouse  by  sim¬ 
ply  reading  and  discarding  bytes  until  one 
with  such  a  pattern  is  found.  The  packets 
then  contain  the  following  data: 

Byte  Contents 

0  10000LMR* 

1  A  Xx 

2  A  Yj 

3  AX2 

4  AY2 _ 

*Left,  middle,  and  right  buttons. 

The  mouse  supports  two  types  of 
protocols:  Rotatable,  and  Non-Rotatable. 
In  the  Rotatable  mode,  the  position  of 
two  sensors  is  transmitted,  which  makes 
it  possible  for  the  interface  program  to 
determine  both  the  rotational  and  transla¬ 
tional  orientation  of  the  mouse.  However, 
in  most  applications  only  the  transla¬ 
tional  information  is  of  interest,  so  the 
Non-Rotatable  protocol  is  used.  The 
mouse’s  two  sensors  then  send  out  redun¬ 
dant  information.  This  also  allows  con¬ 
tinued  operation  in  case  of  failure  of  one 
of  the  LED  sensors. 

XSUB  for  CP/M-86 

Mr.  Terje  Bolstad  of  Elektrokonsult 
has  sent  us  a  pre-release  copy  of  his  com¬ 
pany’s  XSUB  utility  for  CP/M-86.  XSUB 
extends  the  SUBMIT  utility  to  include 
input  to  transient  application  programs 
from  batch  files,  analogous  to  the  XSUB 
which  is  supplied  by  Digital  Research  for 
CP/M-80.  This  can  be  very  useful  for 
automatic  execution  of  tasks  which  re¬ 
quire  long  sequences  of  commands.  For 
example,  you  could  set  up  a  batch  file 
that  would  automatically  format  a  new 
diskette,  copy  the  system  tracks,  and 
then  transfer  selected  files  without  any 
operator  intervention.  Digital  Research’s 
release  of  CP/M-86  without  a  XSUB  was 
the  subject  of  many  heartfelt  complaints 
by  users  who  had  gotten  used  to  that 
capability  under  CP/M-80,  and  I  am  glad 
to  see  an  independent  software  house 
filling  the  gap. 

Incidentally,  Mr.  Bolstad  pointed  out 
some  “features”  of  the  ordinary  SUBMIT. 
CMD  utility  that  are  not  mentioned  in 
the  CP/M-86  documentation.  First,  all 
lines  in  a  submit  file  starting  with  a  semi¬ 
colon  are  treated  by  SUBMIT  as  com¬ 
ments;  i.e.,  they  are  displayed  as  they  are 
encountered  during  the  execution  of  a 
submit  file,  but  no  other  action  is  taken. 


Second,  SUBMIT  will  convert  the  two 
letter  combination  of  an  “A”  followed 
by  an  ASCII  character  A-Z  into  the 
corresponding  control  character.  Third, 
SUBMIT  will  terminate  without  an  error 
message  if  it  encounters  an  empty  line  in 
a  batch  file,  even  if  the  blank  line  is  fol¬ 
lowed  by  valid  command  lines. 

The  XSUB.CMD  utility  is  available 
from  Elektrokonsult  A/S,  Inc.,  Konnerud- 
gaten  3,  N-3000  Drammen,  Norway  for 
$39.00  plus  shipping.  At  present  only 
standard  8-inch  SSSD  and  514-inch  DEC 
Rainbow  disk  formats  are  available. 

IBM  and  Epson 
Printer  Control  Codes 

Dan  Daetwyler,  who  contributed  the 
IBM  PC  graphics  printer  dump  article  in 
June  DDJ,  has  written  with  some  addi¬ 
tional  information  for  those  who  may 
have  run  into  unexpected  problems  with 
it. 

He  says,  “I’ve  learned  the  hard  way 
that  there  is  quite  a  variety  of  ROMs 
available  for  the  Epson  MX80  (and  equiva¬ 
lent  IBM)  printers.  The  current  ‘crunch’ 
is  primarily  the  difference  between  the 
Epson  MX80  with  GRAFTRAX  option 
and  the  ‘IBM  Graphics  Printer.’  The 
following  list  of  differences  between  the 
two  ROMs  may  be  useful  to  your  readers. 
I  can’t  promise  that  only  two  versions  of 
the  ROMs  are  out  in  the  world,  but  at 
least  this  is  a  good  first  step. 

“The  following  DECIMAL  codes  are 
only  active  on  the  GRAFTRAX  ROM 
and  are  not  available  on  the  IBM  Graphics 
Printer: 

35  —  Accept  8  th  bit  as  is 
8  —  Backspace  1 

136  —  Backspace  1 
Esc  61  —  Clear  8  th  bit 

1 27  —  Delete  last  character  in  buffer 

255  —  Delete  last  character  in  buffer 
Esc  53  -  Italics  OFF 
Esc  52  —  Italics  ON 

“The  following  DECIMAL  codes  are 
only  active  on  the  IBM  Graphics  Printer, 
and  are  not  available  on  the  GRAFTRAX 
ROM: 

24  —  Cancel  the  line,  clear  printer 
buffer 

152  —  Cancel  the  line,  clear  printer 
buffer 

Esc  55  —  Character  set  1 
Esc  54  —  Character  set  2 

“The  following  DECIMAL  codes  are 
used  on  both  ROMs  but  function  differ- 
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ently  between  the  two  implementations: 

GRAFTRAX: 

Esc  65  n  —  Set  line  spacing  to  n/72 
inches  (immediate) 

Esc  50  —  Reset  line  spacing  to  default 

(1/6  inch  ) 

IBM  Graphics  Printer: 

Esc  65  n  —  Prepare  line  spacing  to  be 
n/72  inches 

Esc  50  —  Set  line  spacing  as  prepared 

by  Esc  65  n  (If  no  Esc  65 
pending,  defaults  to  1/6  inch  ) 

“These  differences  are  really  minor, 
but  as  my  article  in  the  June  issue  proves, 
can  lead  to  trouble.  I  set  the  SHDGRPH 
program  up  on  a  GRAFTRAX  printer 
and  was  a  bit  less  than  pleased  when  I 
discovered  it  wouldn’t  work  properly 
on  the  IBM  Graphics  Printer.  The  dif¬ 
ference  is  in  the  Esc  65  sequence,  which 
I  used.  I  preset  the  line  spacing  (when 
running  on  the  IBM),  but  never  imple¬ 
ment  until  the  dot  matrix  printing  is 
done.  This  has  the  dual  effect  of  leaving 
white  space  between  each  row  of  eight 
dots,  and  of  leaving  the  printer  in  an  8/72 
inch  line  spacing  at  end  of  job  (Ugh!); 
while  if  I  had  written  the  program  for  the 
IBM  Graphics  Printer,  running  it  on  a 
GRAFTRAX  would  have  printed  the 


With  hardware  floating  point  libraries  from  Micro  Float: 

Language 

Version 

Result 

Time  (sec.) 

PL/I  -86  with  8087 

1.01 

2477.244 

3.7 

8080  Assembler  with  8232 

RMAC 

2499.955 

10.2 

PL/I -80  with  8232 

1.40 

2499.995 

10.4 

BASIC-80  with  8232 

5.20 

2500.000 

10.7 

Fortran -80  with  8232 

3.40 

2499.995 

12.5 

With  standard  floating  point  libraries: 

Language 

Version 

Result 

Time  (sec.) 

BASIC -86  Interpreter 

5.20 

2179.850 

92.2 

Fortran -80 

3.40 

2304.863 

140.8 

BASIC-80  Compiler 

5.20 

2304.860 

140.8 

BASIC-80  Interpreter 

5.20 

2304.860 

174.9 

PL/I -86 

1.01 

1641.758 

179.6 

PL/I -80 

1.30 

1641.758 

254.4 

Table  1. 

Comparisons  of  execution  speed  and  accuracy  for  commonly  available  high- 
level  languages,  with  and  without  hardware  floating  point  support.  The  8087 
and  8232  support  libraries  are  marketed  under  the  names  FLOAT87  and 
FLOAT80,  which  are  trademarks  of  MicroFloat. 

graphics  at  1/6  inch  line  spacing  (white 
space  again)  but  at  least  would  have  left 
the  printer  in  a  reasonable  line  spacing 
mode.  Oh  well. 

“The  sources  of  this  data  are  the 
Epson  GRAFTRAX  manual  and  the  IBM 
Technical  Reference  Manual  (XT  version). 
Both  are  copyrighted  publications,  and 
GRAFTRAX  and  IBM  Graphics  Printer 
are  trademarks  of  the  respective  vendors.” 

Concurrent  CP/M-86  Enhancements 

Like  many  other  early  purchasers  of 
Concurrent  CP/M  for  the  IBM  PC,  I  was 
impressed  with  the  potential  power  of 
this  operating  system  but  dismayed  at  its 
“black  box”  nature.  It  seemed  that  in 
this  case  Digital  Research  had  departed 
from  its  old  policies  of  providing  adequate 
technical  information  for  third  party 
hardware  vendors  and  systems  program- 


horizontal  SYNC  position  of  the  video 
controller.  The  third  Note  gives  the  code 
for  a  patch  to  the  operating  system,  in¬ 
stalled  with  DDT86,  that  allows  you  to 
boot  CCPM  from  a  single  drive. 

Digital  Research  is  also  making  avail¬ 
able  (to  qualified  requestors)  a  set  of 
application  notes  and  example  programs 
for  what  they  term  “Field  Installable 
Device  Drivers.”  This  allows  the  program¬ 
mer  to  link  a  software  driver  for  practically 
any  type  of  peripheral  device  to  the  IBM 
PC’s  CP/M-86  or  Concurrent  CP/M-86 
operating  system  with  a  minimum  of  fuss, 
in  much  the  same  manner  as  the  user- 
installed  driver  capability  now  available 
under  MS-DOS  2.0.  The  literature  they 
sent  me  included  sample  drivers  for  a 
RAMDISK  and  a  Zobex  Hard  Disk. 

Incidentally,  the  much  bally-hooed 
Digital  Research  $60  CP/M-86  for  the 


new  release  of  CP/M-86,  and  the  perform¬ 
ance  of  the  operating  system  is  still  just 
plain  slow.  Perhaps  if  Digital  Research 
had  included  some  of  the  features  they 
added  to  CP/M-80  version  3,  such  as  time 
and  date  stamping  of  files  and  hashed 
directory  searches,  and  thrown  in  a  resi¬ 
dent  COPY  function,  they  might  have 
come  up  with  a  viable  competitor  to  Mi¬ 
crosoft’s  operating  system  —  but  I  can’t 
believe  that  anyone  who  is  used  to  the 
responsiveness  of  PC- DOS  could  ever  be 
satisfied  with  this  incarnation  of  CP/M- 
86.  I  suspect  DRI  is  beginning  to  realize 
that,  too,  for  they  recently  announced 
PC-DOS  versions  of  all  their  language 
compilers. 


mers.  A  particularly  sore  point  was  the  IBM  PC  has  finally  arrived.  This  release 
way  Concurrent  CP/M  takes  over  all  of  was  supposed  to  be  The  Answer  to  Digital 
the  interrupt  vectors,  thereby  precluding  Research’s  previous  problems  in  the  PC 
any  access  to  the  PC’s  ROM  Bios.  Another  marketplace,  and  lure  back  a  sizable  por- 
frequently  heard  complaint  was  the  fact  tion  of  the  users  from  Microsoft’s  PC- 
that  you  couldn’t  boot  up  the  operating  DOS.  Well,  the  new  version  of  CP/M-86 
system  without  a  disk  in  both  drives.  does  include  print  spooling,  a  set  of  GSX 

Digital  Research  has  now  issued  three  graphics  device  drivers,  and  some  fancy 
very  welcome  Application  Notes,  which  new  screen-oriented  utility  programs  for 
are  available  to  registered  owners  of  Con-  device  configuration  and  disk  copying/ 
current  CP/M-86  from  the  Technical  formatting.  The  documentation  is  excel- 
Support  Group  at  P.O.  Box  579,  Pacific  lent,  though  it  is  a  sign  of  the  times  that 
Grove,  CA  93950.  The  first  Note  deals  the  technical  information  which  used  to 
with  access  to  the  ROM  Bios,  and  includes  occupy  90%  of  the  DRI  manuals  is  now 
a  sample  program  to  make  a  call  to  the  relegated  to  a  few  appendices. 

ROM’s  Print  Screen  utility.  The  second  But  when  all  is  said  and  done,  there 

Note  provides  a  program  to  adjust  the  are  really  no  substantive  changes  in  this 
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Circle  no.  20  on  reader  service  card. 
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16-Bit  Toolbox  (Text  begins  on  page  120) 

Listing  One  BASIC  and  PL-1  versions  of  Bill  Savage's  accuracy  and  speed  test  for  high  level  languages. 

100  '  Time  and  General  Accuracy  Test  Program 

110  DEFINT  I 
120  IL00P=2500 

130  A= 1 

140  FOR  1=1  TO  I LOOP- 1 

150  A  =  TAN ( ATN (EXP (LOG (SQR (A*A) ) ) ) )  +  1 
160  NEXT  I 

170  PRINT  USING  "A=#### .####"; A 
180  STOP 


actest : 

proc  options  (main); 

declare  (i,iloop)  fixed  bin(15), 
a  float  bin (24) ; 

top:  a  =  1  ; 

put  skip (2)  list  ('Ending  loop  value  :  '); 

get  list  (iloop); 

if  (iloop  <  2  !  iloop  >3000)  then  goto  top; 
do  i =1  to  iloop-1; 

a  =  tan (atan (exp (log (sqrt (a*a) ) ) > )  +  1.0  ; 
end; 

put  skip  edit  ( ' 1= ' , i , ' A= ' ,a)  (a,f (5) ,a,f  ( 14,8) ) ; 
goto  top; 

end  actest;  End  Listing  One 

Listing  Two 


10  REM  Demonstration  program  for  M-l  Optical  Mouse. 

11  REM  Assumes  "Mouse"  interfaced  through  RS232  port  0. 

12  REM  Run  program,  then  calibrate  mouse  by  sweeping  it 

13  REM  in  wide  circles  until  the  "star"  on  the  screen  moves. 

14  REM  To  leave  a  trai 1  push  any  mouse  button,  to  terminate 

15  REM  the  demonstrat i on  push  all  three  buttons  at  once. 

20  REM  Richard  Wilton  -  January  1983 

30  REM 

40  GOTO  1000 
50  REM 

100  REM  initialize  RS-232  port  for  1200  baud,  no  parity,  8-bit  data 

110  ON  ERROR  GOTO  150 

120  OPEN  "COMO: 1200, N, 8"  AS  #1 

130  ON  ERROR  GOTO  O 

140  RETURN  (Continued  on  next  page) 
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150  REM  come  here  if  comm  port  initialization  times  out 
155  PRINTzPRINT  "comm  port  initialization  failure":  PRINT 
160  RESUME  NEXT 
170  REM 

200  REM  get  a  data  packet  from  the  mouse  interface. 

210  REM  synchronize  by  waiting  for  a  byte  with  bit  pattern  lOOOOx 
220  IF  (INF1  (PI*/.)  AND  1)  THEN  B*/.=  I NP  ( P27. )  :  I F  (B*/.  AND  &H80)  THEN  ELSE 
ELSE  220 

225  REM  now  read  the  two  sets  of  x,y  coordinates. 

230  IF(INP(P17.)  AND  1)  THEN  X1*/.=  INP  (P27.)  ELSE  230 

240  IF(INP(P17.)  AND  1)  THEN  Y17.=  INP  (P27.)  ELSE  240 

250  IF(INP(P17.)  AND  1)  THEN  X2*/.=  INP  (P27.)  ELSE  250 

260  IF(INP(P17.)  AND  1)  THEN  Y2*/.=  I  NP  ( P27. )  ELSE  260 


270 

IF 

XI 7.  >=128  THEN 

THEN  200 

XI 7.= XI 7. 

OR 

C7. 

= 

IF 

X17.< 

-120 

280 

IF 

Y 17.  >=128  THEN 
THEN  200 

Y1"/.=Y17. 

OR 

C7. 

5 

IF 

Y17.< 

-120 

290 

IF 

X 27.  >=128  THEN 
THEN  200 

X2*/.=  X2  7. 

OR 

C7. 

= 

IF 

X2*/.< 

-120 

300 

IF 

Y27.>=128  THEN 
THEN  200 

Y2*/.=Y27. 

OR 

C*/. 

s 

IF 

Y2  7.< 

-120 

310  B*/.=B7.  AND  7 
320  RETURN 
330  REM 

500  REM  initialize  the  screen 
510  CLS 

520  X*/.  =  40  :  Y7.  =  12 

530  LOCATE  Y*/.,X7.  :  PRINT  ; 

540  RETURN 
550  REM 

600  REM  update  the  screen  from  X07,Y07 
610  IF  B*/.=7  THEN  LOCATE  Y7.,X*/.:  PRINT  "  " 

620  IF  XO*/.  >  0  AND  X07.  <  81  THEN  X*/.=X07. 

630  IF  Y07.  >  O  AND  Y07.  <  24  THEN  Y7.=Y07. 

640  LOCATE  Y*/.,X7.  :  PRINT  "*" 

650  RETURN 
660  REM 

900  REM  set  up  constants  and  port  addresses 
910  C*/.=&HFF00 

920  P17.=&H3FD  '  status  port 

930  P2*/.=&H3F8  '  data  port 

940  RETURN 
950  REM 

lOOO  REM  demonstrati  on  program  control  starts  here 
101 O  60SUB  900  ’  initialize  constants  and  port 

addresses 

1020  GOSUB  lOO  ’  initialize  serial  port  for  baud 
rate  etc. 

1030  GOSUB  500  7  initialize  display  screen 

1040  REM  top  of  mouse  tracking  loop 
1045  REM  read  next  change  of  mouse  state 
1050  GOSUB  200 

1055  REM  update  the  mouse  coordinates 
1060  X07.  =  X7.  +  X 1 7.  :  Y07.  =  Y7.  -  Y17.  :  GOSUB  600 
1070  XOV.  =  X 7.  +  X27.  :  VO'/.  =  Y7.  -  Y27.  :  GOSUB  600 
1075  REM  keep  going  until  all  three  buttons  are 
pressed 

1080  IF  B7.X>  THEN  1050 

1090  END  End  Listing  Two 
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x  N 


1  6-Bit  Toolbox  (Listing  continued,  text  begins  on  page  120) 

Listing  Three 


Screen  #  80 

O  (  initialize  mouse 
1 

2  HEX 

3 

4  CODE  I NT 14  (  AX  DX  — 

5  DX  POP  AX  POP  14  INT 

6 

7 

8  :  INIT— MOUSE  (  —  AX  ) 

9  083  O  INT 14  ; 

10 

11  DECIMAL 

12 

13  — > 

14 

15 


01/29/83  ) 


AX  )  (  see  Tech  Ref  p.  A-20  ) 

AX  PUSH  NEXT 


(  set  comma  port  O  to  1200  baud  . .  ) 

(  ..  no  parity,  1  stopbit,  8-bit  data  ) 


Screen  #  81 

0  (  read  data  from  mouse 

1 


2 

FORTH  DEFINITIONS  HEX 

3 

4 

CODE 

©MOUSE  (  —  dX  dY 

dX 

dY 

LMR 

5 

CX,  #  3  MOV 

6 

■  ■ 

* 

DX,  #  3FD  MOV 

AL 

,  DX 

IN 

7 

AL,  #01  AND 

8 

1 *  JZ 

9 

DX,  #  3F8  MOV 

AL 

,  DX 

IN 

10 

AH,  AL  MOV 

1 1 

AX,  CL  SHR 

12 

AH,  #  10  CMP 

13 

1$  JNE 

14 

BL,  AL  MOV 

15 

—  > 

Screen  #  82 

0  (  read  data  from  mouse,  cont. 
1 


2 

CX, 

# 

4  MOV 

3  2T: 

DX  , 

# 

3FD  MOV 

AL, 

DX 

IN 

4 

AL, 

# 

Ol  AND 

5 

2$ 

JZ 

6 

DX  , 

# 

3F8  MOV 

AL, 

DX 

IN 

7  CBW 

8  AX  PUSH 

9  2$  LOOP 

10  BH,  BH  XOR 

11  CL,  #  5  MOV 

12  BL,  CL  SHR 

13  BX  PUSH 

14  NEXT 

15  DECIMAL  — > 


01/29/83  ) 


(  #  bits  for  shift  ) 
(  read  RS-232  LSR  port  ) 
(  wait  for  Data  Ready  ) 

(  read  RS-232  data  port  ) 
(  copy  to  hi -order  byte  ) 
(  put  flag  in  AH,  LMR  in  AL  > 
(  1st  byte  of  data  packet?  ) 
(  try  again  if  not  ) 
(  save  LMR  for  later  ) 


01/29/83  ) 

(  count  for  loop  ) 

(  read  RS-232  LSR  port  ) 

(  wait  for  Data  Ready  ) 

(  read  RS— 232  data  port  ) 

(  sign  extend  ) 

(  push  onto  stack  ) 

(  zero  hi— order  byte  ) 

(  set  #  bits  to  shift  ) 

(  shift  LMR  flags  to  right  ) 

(  push  the  result  ) 

(  c'est  tout  ) 

(Continued  on  next  page) 


126 


Dr.  Dobb’s  Journal,  Number  83,  September  1983 

555 


01/29/83  ) 


Screen  #  83 

0  (  demo  for  optical  mouse 
1 

2  0  VARIABLE  LEFT  (  button  status  -flag  ) 

3 

4  :  DEMO  (  —  ) 

5  INIT-MOUSE  DROP  (  set  comm  port,  ignore  status  > 

6  6  MODE  320  100  2DUP  1  ! dot  (  start  at  center  of  screen  ) 

7  BEGIN  ©MOUSE  -DUP  WHILE 

8  4  AND  4  =  LEFT  !  (  update  button  ) 

9  LEFT  @  IF  6  PICK  6  PICK  0  ! dot  END IF  (  erase  old  x,y  ) 

10  >R  >R  MINUS  ROT  +  >R  +  R>  (  1st  x,y  > 

11  LEFT  @  0=  IF  2DUP  1  ! dot  END IF  (  mark  1st  x,y  ) 

12  R>  R>  MINUS  ROT  +  >R  +  R>  2DUP  1  ! dot  (  2nd  x,y  ) 

13  REPEAT  (  until  all  3  buttons  are  down  ) 

14  2  MODE  2DR0P  2DR0P  2DR0P  ; 

15 

End  Listing  Three 
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OF  INTEREST 


by  Michael  Wiesenberg 


Send  Your  Resume  To 
the  “Job  Registry” 

For  years,  doctors  and  lawyers 
have  had  the  luxury  of  using  their  own 
exclusive  “job  referral  services”  to 
advertise  their  professional  experience 
to  prospective  employers.  But  now, 
thanks  to  a  small  company  in  Hay¬ 
ward,  California,  there  will  soon  be 
available  an  on-line  computer  database 
called  The  Software  Pro’s  Job  Registry. 

This  service  has  actually  been  in 
existence  since  July  1982;  but  as  the 
database  grew,  its  founders  decided  to 
design  the  software  and  hardware  nec¬ 
essary  to  put  the  entire  service  on-line. 
Scheduled  to  be  implemented  in  Febru¬ 
ary  1984,  this  service  will  continue  to 
help  programmers  match  up  their  skills 
and  interests  with  real  jobs.  The  Soft¬ 
ware  Pro’s  Job  Registry  was  started  by 
a  high-tech  marketing  and  advertising 
agency  called  C.  J.  Street  &  Associates, 
and  was  originally  provided  only  to 
programmers  who  understood  the 
Forth  computing  language.  Today, 
however,  this  service  is  extended  to  all 
programmers  with  experience  in  any 
computing  language. 

The  people  who  operate  this  job 
referral  service  are  now  advertising  for 
new  members;  and,  as  part  of  the  ser¬ 
vice,  they  also  publish  an  occasional 
newsletter.  However,  the  membership 
fee  is  a  ghastly  one  dollar.  So,  if  the 
price  doesn’t  scare  you  away,  and 
you’re  still  interested,  send  a  self- 
addressed,  stamped  envelope  to:  The 
Software  Pro’s  Job  Registry,  c/o  C.J. 
Street  &  Associates,  24301  Southland 
Drive,  No.  216,  Hayward,  CA  94545 ; 
or  call  (415)  887-2687. 


Tiny  TV  and  Tinier  Computer 

Casio,  a  company  that  makes  all 
kinds  of  tiny  electronic  miracles,  has 
introduced  Casiovision,  the  world’s 
smallest  (3.19-by-4.69-by-l-inches  in  di¬ 
mension,  and  weighing  a  mere  12.35 
ounces)  pocket  television.  It  has  a 
2.75 -inch  screen  and  a  display  element 
that  is  a  twisted  nematic  type  of  liquid 
crystal.  The  screen  can  be  seen  equally 
well  in  the  dark  (because  of  an  electro¬ 
luminescent  backlight)  as  out  in  the 
bright  sunlight  (because  of  its  trans¬ 


lucent  high-resolution  LCD  with  high 
duty  dual  matrix  drive  system).  Casio¬ 
vision  has  four  modes  of  power  supply: 
AC  adapter,  DC  (three  AA  batteries), 
car  battery,  and  rechargeable  nickel 
cadmium  battery.  It  has  an  earphone 
jack  and  its  own  speaker,  and  costs 
$299.  Not  only  can  you  hold  an  ice 
cream  cone  in  one  hand  and  this  tiny 
TV  in  the  other;  but  (and  here’s  why 
I  mention  it)  suddenly  the  technology 
for  very  tiny  computer  monitors  exists. 

Casio  has  also  entered  the  medium- 
priced  notebook  computer  and  hand¬ 
held  computer  fields.  The  FP-20  has  a 
20-column  by  8-line  display  for  data 
and  graphic  information.  It  comes 
standard  with  8K  RAM  (expandable  to 
32K)  and  32K  ROM  (expandable  to 
40K),  BASIC,  a  built-in  spreadsheet 
program,  a  full-size  keyboard,  RS-232 
and  Centronics-compatible  parallel 
ports,  weighs  under  four  pounds, 
measures  12.4-by-8.8-by-2.2-inches. 
The  FP-20  runs  on  batteries  or  AC, 
and  costs  $499.  The  FX-802PAC 
hand-held  computer  has  cassette  inter¬ 
face  and  a  built  in  thermal  printer,  2K 
RAM,  BASIC,  and  costs  $189.90.  On 
top  of  all  this,  Casio  has  a  software 
library  for  the  HHC  with  over  50  pro¬ 
grams  in  prices  that  range  from  $15 
to  $35.  Reader  Service  No.  103. 


Developing  for  CROMIX 

Model  CXDR  from  Cromemco  is  a 
development  system  for  systems  inte¬ 
grators  and  others  to  develop  custom 
I/O  drivers  for  CROMIX  —  the  multi¬ 
user,  multi-tasking  UNIX-like  operat¬ 
ing  system.  The  accompanying  docu¬ 
mentation  describes  how  to  add  char¬ 
acter  device  drivers  and  explains  how 
primary  driver  subroutines  are  handled. 
It  also  details  utilities  to  add  and  re¬ 
move  interrupt  vectors,  transfer  and 
buffer  characters,  sleep,  wake  up,  and 
interface  with  the  TUART.  The  soft¬ 
ware  can  be  used  with  Z80  CROMIX 
and  the  68000/Z80  CROMIX-D  dual 
processor  operating  system.  Cromem¬ 
co  particularly  recommends  the  sys¬ 
tem  for  those  using  the  real-time  con¬ 
trol  capabilities  of  CROMIX,  and  for 
those  who  wish  to  interface  to  spe¬ 
cialized  sensing  or  electronically  con¬ 


trolled  devices.  $595.  Reader  Service 
No.  105. 


Color  It  Three  Inches 

Amdisk  III,  from  Amdek,  is  a 
three -inch  dual  disk  drive  for  the 
Radio  Shack  Color  Computer.  It’s 
completely  compatible  with  TRSDOS. 
The  drives  provide  up  to  624K  double¬ 
density  formatted  storage  for  $599; 
and,  they  say,  “the  media  is  $6.99 
each.”  Or  did  they  mean,  “the  medi¬ 
um  is  $6.99  each”?  Reader  Service 
No.  107. 


Old  Rumor  Confirmed 

A  long  time  ago,  I  hinted  at  the 
possibility  of  using  CP/M  on  the  Atari 
400  or  800.  A  reader  wrote  in  asking 
for  more  information,  which  I  was 
unable  to  supply  because  I  had  been 
sworn  not  to  reveal  the  source  of  my 
leak.  However,  now  comes  an  an¬ 
nouncement  from  USS  Enterprises 
(clever,  huh,  Trekkies?)  of  the  im¬ 
proved  Critical  Connection,  an  inter¬ 
face  that  allows  the  Atari  to  use  the 
disk  drives,  printer,  and  keyboard  of 
any  CP/M  system  with  a  19.2  Kbaud 
serial  port.  The  system  is  configured 
for  Kaypro,  North  Star,  Sanyo,  some 
Cromemcos,  CCS,  Heath-Zenith,  and 
Morrow.  You  get  hardware  to  connect 
the  CP/M  system  to  the  Atari,  soft¬ 
ware  on  various  formats,  simulation  of 
four  Atari  disK  drives,  software  buffers 
for  CP/ M  keyboard  and  printer,  error 
detection  and  recovery,  documenta¬ 
tion,  and  technical  support.  You  can 
write  and  edit  Atari  programs  on 
either  system,  and  store  them  on  the 
CP/M  disk  drives,  or  print  them  out  on 
the  CP/M  printer.  $175,  and  you  can 
get  a  free  brochure.  Reader  Service 
No.  109. 


Public  Domain  PC  Software 

Now,  you  can  buy  a  book  that’ll 
show  you  how  to  get  public  domain 
software  for  your  PC-DOS.  The  New 
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York  Amateur  Computer  Club  (NYACC) 
has  a  library  out  that  includes  lan¬ 
guages,  applications,  utilities,  games, 
and  more,  all  listed  in  their  Catalog  of 
Public  Domain  Software  for  PC- DOS, 
Book  1,  one  of  several  catalogs  availa¬ 
ble  by  mail  from  the  NYACC.  This 
catalog  costs  $  10  in  North  America 
and  $15  for  overseas  airmail  (U.S. 
funds).  The  catalog  lists  the  first  26 
volumes  in  the  PC/Blue  Public  Domain 
Library,  with  tables  of  contents  and 
abstracts  of  files,  and  all  document  files 
contained  on  the  diskette  volumes.  To 
get  the  diskettes,  send  $6  (per  diskette) 
to:  NYACC,  P.O.  Box  106,  Church  St. 
Station,  New  York,  NY  10008.  Also 
available  at  the  same  price  is  the  Cata¬ 
log  of  Public  Domain  Software  for 
CP/M,  Books  1  through  8.  Each  lists 
the  contents  of  scores  of  volumes, 
with  such  goodies  as  software  tools 
from  Australia,  programs  from  the 
PL/ 1  and  Pascal  Z  Users’  Groups, 
68000  cross  assembler,  an  update  of 
MODEM7,  as  well  as  CP/M-86  utilities, 
a  Z80  Command  Processor  Replace¬ 
ment,  and  more  .  .  .  including  contri¬ 
butions  from  SIG/M.  Reader  Service 
No.  111. 


Standard  Bulletin  Board 

The  Commerce  Department’s  Na¬ 
tional  Bureau  of  Standards  has  estab¬ 
lished  a  computer  bulletin  board,  the 
Microcomputer  Electronic  Informa¬ 
tion  Exchange  (MEIE),  for  topics 
about  micros.  This  bulletin  board  pro¬ 
vides  information  on  conferences,  sem¬ 
inars,  workshops,  telecomputing  ser¬ 
vices,  user  and  special  interest  groups, 
other  CBBs,  publications,  new  com¬ 
puter  products,  and  technology.  You 
don’t  have  to  be  part  of  the  govern¬ 
ment  to  use  the  bulletin  board,  and  it’s 
free;  all  you  need  is  an  ASCII  terminal, 
with  eight  data  bits,  no  parity  and  one 
stop  bit.  Call  (301)  948-5718  any  time 
to  access  the  service,  or  (301)  948-5717 
to  reach  a  bulletin  board  devoted  to 
exchanging  information  on  computer 
performance  evaluation  topics.  Reader 
Service  No.  1 13. 


Lots  of  Shows 

Northeast  Expositions  announces 
the  following  computer  shows: 

The  Second  Annual  Twin  Cities 
Computer  Show  and  Software  Expo¬ 
sition  will  be  held  September  15-18 
at  the  Minneapolis  Auditorium  in 
Minneapolis,  Minnesota.  This  is  “the 
largest  annual  computer  exposition 


in  the  north  central  states,  and  fea¬ 
tures  350  displays.”  Daily  admission  is 
$5  for  adults,  $3  for  children.  Reader 
Service  No.  115. 

The  Second  Annual  Rocky  Moun¬ 
tain  Computer  Show  and  Software 
Exposition  will  be  held  September  22- 
24  at  the  Denver  Merchandise  Mart. 
This  is  “the  largest  annual  computer 
exposition  in  the  Rocky  Mountain 
states,  and  features  350  displays.” 
Daily  admission  is  also  $5  for  adults 
and  $3  for  children.  Reader  Service 
No.  117. 

CP/M  ’83  East  will  be  held  Sep¬ 
tember  29  -  October  1  at  Boston’s 
Hynes  Auditorium.  The  Exposition 
portion  of  the  event  has  been  said 
to  be  “the  largest  presentation  of 
CP/M  hardware  and  software  ever 
assembled.”  The  Conference  Program 
features  nearly  100  sessions,  including 
such  “noted  leaders  from  the  software 
industry”  as  Gary  Kildall,  Sol  Libes, 
Stewart  Alsop  (he’s  in  the  software 
industry?),  and  Benjamin  Rosen.  Tick¬ 
ets  are  $25  for  three  days  of  exhibits 
and  conferences,  or  $  10  for  a  one-day 
ticket  for  the  exhibits  only.  Reader 
Service  No.  119. 

And,  while  you’re  in  the  area, 

PC  ’83  will  be  held  October  8-10  at 
Boston’s  Bayside  Exposition  Center. 
Tickets  are  $25  for  three  days,  or  $  10 
for  a  one-day,  exhibits-only  ticket. 
Reader  Service  No.  121. 

Meanwhile,  on  the  other  side  of 
the  country,  Applefest/San  Francisco, 
the  largest  Apple  computer  show  in 
the  U.S.,  will  be  held  October  28-30 
at  the  Moscone  Center.  Events  will 
include  an  open  forum  with  Steve 
Wozniak  and  a  panel  discussion  with 
software  experts  on  “The  Great 
Software  Piracy  Debate.”  Tickets  are 
$25  for  three  days  of  exhibits  and  con¬ 
ferences,  or  $10  for  one  day  of  exhi¬ 
bits  only.  Reader  Service  No.  123. 

And,  if  you’re  still  hanging  around 
Boston,  the  Fifth  Annual  Northeast 
Computer  Show  and  Software  Expo¬ 
sition  will  be  held  November  10- 12  at 
Boston’s  Hynes  Auditorium.  This, 
they  claim,  will  be  the  “largest  annual 
end-user  computer  event  in  the  East.” 
(This  falls  into  the  same  category  as 
such  statistics  as  “most  home  runs  hit 
in  the  third  inning  of  the  third  game  of 
the  World  Series  by  a  switch-hitter 
against  a  left-hander  with  the  sun  in 
his  eyes  and  the  score  tied.”)  There 
will  be  approximately  500  displays 
and  exhibits.  Daily  admission  is  $7.50. 
Reader  Service  No.  125. 

The  Fourth  Annual  San  Diego 
Computer  Fair,  sponsored  by  the  San 
Diego  Computer  Society,  will  be  held 
November  5  and  6  at  the  Scottish  Rite 


Center.  Registration  is  $5 ;  there’s  a 
banquet,  $12;  or  both  for  $17.  The 
banquet  will  feature  a  speech  by 
Wright  State  University  engineering 
department  researcher  Dr.  Jerrold 
Petrofsky  about  his  computerized 
method  of  transmitting  electrical  im¬ 
pulses  to  the  muscles  of  paraplegics. 
Reader  Service  No.  127. 


Software  Maintenance  Workshop 
A  Software  Maintenance  Workshop 
will  be  held  from  December  6  to  8  at 
the  Naval  Postgraduate  School  in 
Monterey,  California.  The  workshop 
is  being  sponsored  by  the  Technical 
Committee  on  Software  Engineering, 
the  National  Bureau  of  Standards, 
and  the  IEEE  Computer  Society. 
Reader  Service  No.  129. 


XFORTH  XCHANGE 

A  small  company  in  Little  Rock, 
Arkansas  called  “HAWG  WILD  Soft¬ 
ware”  recently  announced  a  new 
“forum  for  the  exchange  of  ideas” 
among  users  of  their  new  XFORTH, 
Forth-79  software  package.  “No  idea 
is  too  small,  too  large,  or  too  unusual,” 
claims  a  yellow  index -card -sized  press 
release  that  we  received  in  the  mail  last 
week.  The  service  is  free  and  unrestric¬ 
ted.  Send  your  questions  and  imple¬ 
mentations  to:  XFORTH  XCHANGE, 
c/o  HAWG  WILD  Software,  P.O.  Box 
7668,  Little  Rock,  A R  72217. 
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other  off-the-shelf  applications.  Many  of 
these  programs  depend  on  efficient  data 
retrieval  rather  than  sequential  file  trans¬ 
formations. 

If  CP/M  Plus  had  taken  into  account 
the  special  cases  that  arise  during  program 
development,  would  the  OS  run  signifi¬ 
cantly  faster  than  it  does?  I  doubt  it. 
Some  general  rules  for  optimizing  the 
performance  of  operating  systems  are: 
concentrate  on  improving  those  things 
that  are  slow,  not  those  that  are  already 
efficient;  solve  the  general  problem,  not 
specific  instances;  and  optimize  the 
execution  of  individual,  time-consuming 
programs,  instead  of  trying  to  anticipate 
future  command  sequences.  Here’s  what 
CP/M  Plus  does  to  improve  the  perfor¬ 
mance  of  application  programs: 

First,  CP/M  2.2  disk  delays  fall  into 
three  categories.  The  worst  bottleneck 
comes  when  searching  disk  directories. 
Relatively  little  data  are  transferred,  but 
moving  the  head  and  scanning  multiple 
sectors  to  find  the  file  control  block 
make  this  operation  very  slow.  CP/M  Plus 
implements  a  fascinating  scheme  of 
hashed  directory  tables  and  a  separate 
pool  of  directory  sector  buffers  to  elimi¬ 
nate  most  of  this  activity. 

A  second,  lesser  bottleneck  results 
when  programs  do  a  lot  of  direct  record 
accessing,  which  requires  head  movement 
and  rotational  latency  delays.  This  is 
where  the  CP/M  Plus  LRU  buffering 
scheme  comes  into  play,  by  eliminating 
repeated  accesses  to  particular  sectors. 
Statistically  speaking,  you  can  generally 
enhance  the  performance  of  direct  sector 
accessing  by  allocating  more  buffer  con¬ 
trol  blocks.  This  does  not  mean  each 
additional  buffer  decreases  disk  activity 
by  some  measurable  amount. 

The  third  category,  for  which  CP/M 
has  always  been  relatively  fast,  is  reading 
and  writing  logically  sequential  records. 
The  CP/M  record  pre-allocation  scheme 
already  minimizes  head  movement  and 
rotational  latency  in  this  case.  LRU  buf¬ 
fering  cannot,  in  general,  improve  perfor¬ 
mance  for  sequential  files,  since  reading 
or  writing  a  particular  record  virtually 
guarantees  that  a  lot  more  disk  activity 
will  occur  before  the  same  record  is  ac¬ 
cessed  again.  Of  course,  the  record  may 
never  be  accessed  again,  and  any  time 
consumed  when  buffering  it  would  be 
wasted.  Memory  caches  are  normally 
small  relative  to  the  potential  combined 
length  of  the  files  generated  during  a 
work  session.  If  so,  it  makes  perfectly 
good  sense  to  me  to  reserve  sector  buffers 
for  when  they  will  do  the  most  good, 
instead  of  wiping  them  clean  for  a  single 
file. 


One  way  sequential  file  performance 
can  be  improved,  however,  is  by  prefetch¬ 
ing  successive  records  when  a  disk  sector 
is  read.  In  essence,  CP/M  Plus  does  exact¬ 
ly  this  when  multiple  logical  records  are 
blocked  into  each  physical  sector.  CP/M 
Plus  can  greatly  improve  the  reading  or 
writing  of  multiple  sequential  records, 
but  for  this  the  host  system  hardware 
must  be  able  to  transfer  a  series  of  se¬ 
quential  or  adjacent  physical  sectors,  and 
the  application  program  must  be  designed 
to  take  advantage  of  the  new  capability. 

I  can  understand  and  sympathize 
with  Mr.  Cortesi’s  disappointment  that 
adding  a  lot  of  memory  cards  didn’t  seem 
to  help  his  system’s  performance.  But 
which  of  the  CP/M  Plus  performance  im¬ 
provements  was  he  testing?  Not  directory 
searches,  because  his  tests  opened  just  a 
handful  of  files.  Not  direct  sector  access¬ 
ing,  because  he  admitted,  “We  haven’t 
tried  any  direct-access  I/O  yet.” 

The  test  programs  that  he  described 
all  loaded  sequentially,  read  input  files  se¬ 
quentially,  and  wrote  output  files  sequen¬ 
tially.  Mr.  Cortesi  found  that  these  pro¬ 
grams  ran  essentially  as  fast  as  they  had 
under  CP/M  2.2.  The  column  doesn’t 
describe  the  CP/M  2.2  system  used  for 
the  comparison,  but  I  would  guess  the  se¬ 
quential  optimization  of  record  blocking 
and  deblocking  is  implemented  within  its 
BIOS.  If  so,  I  am  not  surprised  that  both 
systems  perform  the  same. 

The  engineers  at  Digital  Research 
could  have  chosen  not  to  override  the 
LRU  scheme  for  sequential  file  accesses. 
This  probably  would  have  improved  the 
operating  system’s  apparent  performance 
somewhat  when  assembling  short  (sequen¬ 
tial)  source  files.  I’m  not  too  concerned, 
though,  with  optimizing  the  performance 
of  programs  that  only  take  25  seconds 
to  complete  anyway.  It’s  much  more  in¬ 
triguing  to  me  that  CP/M  Plus  can  reduce 
an  eight  minute  PL/ 1  compilation  to  five 
minutes,  or  sort  and  merge  a  dozen  raw 
data  files  with  an  existing  database  pro¬ 
gram  in  four  minutes  instead  of  fourteen. 

Near  the  end  of  the  column,  Mr.  Cor¬ 
tesi  makes  some  suggestions  for  further 
improvement.  One  is  to  encourage  the 
retention  of  COM  files  in  memory.  CP/M 
Plus  can  buffer  the  entire  CCP.COM  file 
(which  executes  about  as  often  as  all 
others  put  together)  in  a  reserved  portion 
of  RAM,  so  it  reloads  instantly.  The  OS 
loads  other  COM  files  using  the  high-speed 
multiple -sector  I/O  capability. 

Mr.  Cortesi  also  outlines  an  alternate 
LRU  scheme  that  buffers  all  sectors 
written  sequentially,  but  would  be  over¬ 
ridden  for  sequential  reads.  “Eventually 
the  input  requests  would  work  around  to 
the  sectors  that  had  not  been  displaced,” 
and  from  there  on,  “operate  at  RAM 
speeds.”  he  claims. 


Not  quite.  Output  produced  while 
reading  in  the  early  sectors  would  over¬ 
write  the  remaining  sectors,  producing 
the  same  undesirable  ripple  effect  that  dis¬ 
cards  each  sector  just  before  it’s  needed.  I 
strongly  suspect  that  neither  this  scheme, 
nor  the  proposal  of  heuristically  shifting 
sector  buffers  between  input  and  output 
pools,  would  make  much  difference  in 
the  long  run  for  most  real-world  applica¬ 
tions. 

Despite  these  objections,  1  fully 
agree  with  Mr.  Cortesi’s  final  conclusion, 
which  seems  to  be  that  CP/M  Plus  is 
worth  having,  but  one  should  not  go  over¬ 
board  in  allocating  data  sector  buffers. 

CP/M  Plus  has  many  advantages  over 
CP/M  2.2  aside  from  performance.  Per¬ 
haps  in  future  columns  Mr.  Cortesi  could 
give  us  his  impressions  of  the  more  versa¬ 
tile  CCP,  automatic  diskette  log-in,  alter¬ 
nate  drive  search  chains,  file  time  and 
date  stamping,  implicit  execution  of  sub¬ 
mit  files,  a  larger  TPA,  the  improved 
documentation,  the  on-line  HELP  facility, 
and  so  on.  I’m  sure  your  readers  would 
find  his  views  on  these  topics  most 
interesting. 

Sincerely, 

John  H.  Wharton 
Applications  Research 
P.  O.  Box  2038 
Sunnyvale,  CA  94087 
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LETTERS 


Grigonis  Reconsidered 

To  the  editor: 

When  I  first  undertook  to  challenge 
certain  points  made  by  Richard  Grigonis 
in  his  article,  “Fifth  Generation  Comput¬ 
ers,”  ( DDJ  #74)  with  my  own  article, 
“Comments  on  ‘Fifth  Generation  Com¬ 
puters’  ”  (DDJ  #77),  little  did  I  realize 
what  1  was  getting  myself  into.  No  one  at 
DDJ  warned  me  that  dissenting  writers 
must  do  battle  with  superhuman  intel¬ 
lects!  Grigonis’s  latest  article,  “And  Still 
More  Fifth  Generation  Computers,” 
(DDJ  #82)  is  utterly  devastating.  Upon 
seeing  an  advance  copy  of  the  manuscript 
sent  to  me  by  Grigonis  himself  (no  doubt 
accompanied  by  a  few  chuckles)  I  now 
find  myself  much  in  the  situation  that  the 
character  of  Turnus  found  himself  in 
Virgil’s  Aeneid,  when  he  attempted  to  do 
away  with  Aeneas  with  one  mighty  blow, 
only  to  find  that  his  sword  merely  shat¬ 
tered  in  his  hands! 

One  rarely  enjoys  recanting  one’s 
ideas  made  in  print,  and  I  must  grudging¬ 
ly  admit  that  Grigonis  has  pretty  much 
blown  my  arguments  to  bits,  although  I 
still  think  that  he  has  not  adequately 
addressed  the  question  of  program  valida¬ 
tion  in  his  actor-based  language/program 
generator.  No  matter  —  1  dare  not  taunt 
him  or  he  will  undoubtedly  wreak  havoc 
once  again  upon  my  carefully  thought-out 
arguments. 

The  first  part  of  the  article,  which  I 
think  amazes  me  more  than  anything  I 
have  read  in  DDJ  (or  anywhere  else)  in  a 
long  time,  is  a  succinct,  astute  analysis 
that  ranges  over  everything  from  soup  to 
nuts.  First  he  cleverly  makes  a  fool  out  of 
me  by  pointing  out  that  the  speed  of  light 
dictates  that  all  computers  of  increasing 
speed  must  ultimately  be  either  micro¬ 
computers  or  the  size  of  microcomputers, 
then  he  goes  on  to  casually  mention  what 
the  ultimate  limits  of  computation  are  in 
the  physical  world  (as  if  we  had  known 
all  along),  then  he  literally  humiliates  the 
Japanese  in  a  brilliant  analysis  revealing  a 
“fatal  flaw”  (namely,  the  PROLOG  lan¬ 
guage  and  the  predicate  logic  knowledge 
representation  scheme  upon  which  it  is 
based)  in  their  billion -dollar  effort  to 
produce  their  own  version  of  a  fifth  gen¬ 
eration  computer,  and  then  he  plausibly 
describes  his  own  ideas  for  both  comput¬ 
ers  and  the  workstations  for  the  next  half 
century  with  such  clarity  and  detail  that  I 
think  he  must  have  a  crystal  ball  powered 
by  a  16  MHz  Motorola  68000! 


But  before  we  hastily  give  Mr.  Gri¬ 
gonis  a  MacArthur  Award  for  his  sheer 
intellectual  virtuosity,  there  are  a  few 
remaining  items  that  I  would  still  like  to 
challenge  him  on  —  although  (understand¬ 
ably)  I  do  so  with  the  utmost  apprehen¬ 
sion! 

The  PROLOG  language  may  not  be 
as  bad  as  Grigonis  thinks.  Since  last  year 
there  have  been  three  major  revisions  in 
PROLOG  (nobody  will  say  what  they  are, 
however)  and  the  Japanese  are  working 
on  some  kind  of  processor  using  the 
molecules  in  a  crystal  lattice  as  flip/flop 
switches,  something  roughly  along  the 
lines  Grigonis  suggests  when  he  talks 
about  “optical”  microprocessors.  An 
ideal  processor  based  upon  a  new  architec¬ 
ture  would  execute  PROLOG  statements 
directly  (like  the  MicroPascal  Engine)  in¬ 
stead  of  first  compiling  all  the  statements 
to  machine  code. 

Another  reason  for  using  PROLOG,  I 
think,  is  that  whereas  LISP  programs  are 
very  formula-like,  and  writing  artificial 
intelligence  programs  in  it  is  more  of  an 
art  than  a  science,  programmable  logic  is 
modular  and  large  numbers  of  people  can 
work  on  a  giant  AI  program  simultane¬ 
ously.  This  fits  in  well  with  the  Japanese 
work  ethic,  where  individual  creativity  is 
sublimated  to  that  of  team  work. 

I  myself  am  interested  in  Forth  as  a 
language,  since  it  runs  much  faster  than 
LISP,  and  is  extensible  so  it  could  in 
theory  be  given  LISP-like  functions.  But 
logic  seems  to  dictate  that  LISP  is  the 
correct  language  for  use  in  artificial  intel¬ 
ligence.  I  would  be  interested  in  seeing 
Grigoinis’s  thoughts  upon  the  matter 
(Gulp ! ). 

It’s  interesting  that  Grigonis  should 
pick  an  arch  as  the  basic  shape  for  his 
workstation,  since  the  arch  is  an  impor¬ 
tant  symbol  or  “archetype”  (no  pun 
intended)  in  Jungian  dream  analysis, 
wherein  it  represents  a  major  change  or 
revelation.  For  this  reason  artists  subcon¬ 
sciously  use  it  in  their  work.  For  example, 
at  the  climactic  end  of  the  motion  picture 
Mildred  Pierce,  Mildred  and  her  husband 
walk  off  into  a  sunrise  that  is  pouring 
through  an  arch  in  the  distance.  There  is, 
in  fact,  a  whole  “dream-like”  quality  to 
the  exterior  design  of  the  Grigonis  work¬ 
station.  Whether  Grigonis  designed  it  that 
way  to  lull  the  user  or  whether  he  literal¬ 
ly  dreams  up  these  designs  remains  to  be 
seen! 

Grigonis  and  I  are  definitely  in  total 
agreement  on  one  thing,  and  that  is  the 


disturbing  sociological  effects  of  super- 
intelligent  computers  and  the  information 
explosion.  But  whereas  I  have  grave  fears 
for  the  well-being  of  America,  Grigonis 
seems  to  take  it  all  in  stride.  And  this 
leads  me  to  the  most  puzzling  and  dis¬ 
turbing  aspects  of  his  article  found  in  its 
concluding  paragraphs. 

The  first  part  of  the  article  is  pretty 
much  upbeat,  and  Grigonis’s  arguments 
are  so  extraordinarily  simple  that  they 
border  on  genius.  It’s  the  “2000  AND 
BEYOND”  part  at  the  end  that’s  got  me 
worried.  After  reading  the  first  part  of 
the  article,  I  expected  that  the  last  sec¬ 
tion  was  going  to  be  an  equally  optimistic 
view  of  how  the  world  would  enter  some 
kind  of  wonderful  technological  utopia 
as  a  result  of  the  development  of  the  ad¬ 
vanced  hardware  and  software  that  he 
describes. 

Much  to  my  horror,  Grigonis’s  logical 
progression  leads  him  to  make  some 
rather  disturbing  statements  regarding  de¬ 
humanization  or  “robotization”  (to  bor¬ 
row  a  term  from  the  late  Arthur  Koestler) 
and  other  similar  nasty  effects  on  civiliza¬ 
tion  as  we  know  it.  I  am  in  agreement 
with  some  of  these  points  and  would  like 
to  refute  some  of  the  others,  but  I  now 
have  some  experience  in  what  happens 
when  somebody  tries  to  refute  Richard 
Grigonis! 

So,  on  the  one  hand,  I  would  like  to 
take  my  hat  off  to  Grigonis,  but  on  the 
other,  I  think  that  perhaps  he  would 
secretly  prefer  a  world  scenario  on  the 
order  of  that  found  in  the  movie,  Colos¬ 
sus:  The  Forbin  Project ! 

Sincerely, 

Michael  J.  Doherty 
334  South  Maple  Avenue 
Glen  Rock,  NJ  07452 

Sleight-of-Hand 
Has  Slight  Problem 

Dear  Doctor: 

The  June  ’83  DDJ  finally  worked  its 
way  around  the  loan  loop  to  me.  (I  really 
ought  to  get  a  subscription....)  I  read 
with  some  interest  Do-While  Jones’s  arti¬ 
cle  on  how  to  trace  through  the  BDOS 
despite  the  problems  I  pointed  out  in  my 
Feb.  ’83  letter  on  the  topic.  I  must  give 
him/her  credit  for  a  good  trick,  but  un¬ 
fortunately  (as  a  great  many  of  those  who 
tried  it  have  undoubtedly  discovered),  it 
will  not  always  work. 

The  “two  systems  in  memory  at 
once”  sleight-of-hand  trick  is  very  similar 
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to  the  technique  I  use  to  debug  device 
drivers,  and  is  subject  to  the  same  restric¬ 
tions.  Namely,  no  “magic”  of  any  sort  is 
allowed  to  occur  in  the  debugger  system. 
Basic  vanilla  CP/M  systems  will  not  have 
any  trouble,  but  “high  performance” 
systems  that  use  interrupts,  memory 
management,  and  possibly  DMA  will 
experience  anomalous  behavior.  Consider 
the  problems  of  having  two  copies  of  a 
BIOS  trying  to  field  the  same  interrupt. 
Obviously,  only  one  will  really  get  it.  The 
other  will  probably  hang.  An  even  nastier 
situation  occurs  if  you  have  memory 
management  hardware  that  overlays  part 
of  the  TPA  to  implement  a  TURBO  or 
MEMDISK  buffer  cache.  If  the  second 
copy  of  the  system  happens  to  be  switched 
out  at  the  wrong  time. ...  A  variant  of 
the  above  problem  may  also  occur  with 
certain  portable  systems.  Because  the  ma¬ 
chines  always  have  a  full  complement  of 
memory,  they  do  not  need  to  distribute 
MOVCPM  or  source  to  the  BIOS.  This 
makes  it  difficult  to  build  the  two  copies 
needed.  If  you  could  manage  to  build  the 
two  systems,  the  second  would  probably 
not  work  because  the  RAM/ ROM  bank¬ 
ing  (used  to  maximize  the  size  of  the  TPA) 
could  not  be  relocated. 

The  “two-at-once”  trick  will  work 
quite  nicely  given  that  you  know  enough 
about  the  insides  of  your  system  to  guar¬ 
antee  that  there  will  not  be  any  (adverse) 
interaction  between  two  copies  in  mem¬ 


ory  simultaneously. 

Stephen  M.  Kenton 
Software  Consultant 
475  College 
Norman,  OK  73069 
Fast  Divisibility 
Algorithms  Revisited 
Editor,  DDJ 

The  letter  submitted  by  Prof.  Grin- 
stein  in  DDJ  #82  has  one  untestable 
proposition:  that  my  note  on  divisibility 
in  DDJ  #80  would  have  displeased  Archi¬ 
medes  and  Newton.  Another  proposition, 
that  mathematics  has  many  followers,  is 
imprecise  since  “follower”  is  not  defined. 
The  derogatory  tone  of  the  letter  suggests 
that  it  includes  Dr.  Grinstein,  all  mathe¬ 
maticians,  and  perhaps  all  who’ve  had  a 
course  in  number  theory,  but  does  not 
include  me!  I  am  not  offended  to  learn 
that  I  am  part  of  the  much  larger  set  of 
interested  amateurs,  which  probably  in¬ 
cludes  many  other  DDT  readers.  John  Ka- 
hila  wrote  me  a  friendly  letter,  pointing 
out  that  divisibility  algorithms  are  indeed 
of  ancient  origin,  and  were  fully  general¬ 
ized  by  Pascal,  Fermat,  and  Gauss.  How¬ 
ever,  it’s  likely  that  no  one  has  yet  used 
these  abstract  principles  to  devise  work¬ 
ing  algorithms  for  divisibility  by  many 
(let  alone  all] )  prime  numbers,  since  they 
would  be  very  complex  and  not  very  use¬ 
ful.  The  purpose  of  my  very  brief  article 
was  to  arouse  interest  in  a  few  easy  algo¬ 
rithms,  for  which  someone  might  find 


new  uses.  I  am  unable  to  comprehend 
why  it  should  elicit  such  an  emotional 
response.  The  purpose  of  this  reply  is  to 
encourage  my  fellow  amateurs  to  explore 
possible  uses  of  elementary  math  without 
fear  of  attack  by  lower  echelons  of  the 
mathematical  elite  (its  Archimedian  levels 
will  simply  ignore  such  trivia!).  I  also 
wanted  to  express  my  hope  that  the  edi¬ 
tors  of  DDJ  will  not  be  cowed  into  sub¬ 
jection  of  amateur  contributions  to  the 
imprimatur  of  censors. 

Sincerely, 

H.  T.  Gordon 

College  of  Natural  Resources 
U.  C.  Berkeley 
Berkeley,  C A  94720 

Expanding  Upon  Gordon’s 
Fast  Divisibility  Algorithms 

Dear  Dr.  Dobb’s: 

I  just  read  H.T.  Gordon’s  article  “Fast 
Divisibility  Algorithms”  in  a  friend’s  copy 
of  the  June  1983  issue  (#80).  The  article 
is  well-written  and  interesting;  it  also  illus¬ 
trates  to  some  extent  the  perils  of  trying 
to  do  a  literature  search  in  an  unfamiliar 
field. 

The  divisibility  algorithms  mentioned 
by  Gordon  are  not  new  (as  Gordon  him¬ 
self  suspects).  According  to  L.E.  Dickson 
{History  of  the  Theory  of  Numbers,  vol.  I, 
ch.  XII;  Chelsea  Publications,  1971),  the 
first  hint  of  the  divisibility-by-7  test  ap¬ 
pears  in  the  Babylonian  Talmud,  where  it 
is  noted  that  lOOa+b  is  divisible  by  7  if 
(Continued  on  page  123) 


EDITORIAL - 

i 


This  month,  Anthony  Skjellum  presents  his  first  install¬ 
ment  of  the  C/Unix  Programmer’s  Notebook  —  our  new  bi¬ 
monthly  column  dedicated  to  the  C  language  and  its  deriva¬ 
tives,  and  to  the  Unix  operating  system  and  its  look-alikes. 
The  scope  is  intended  to  be  broad,  and,  as  with  all  DDJ  col¬ 
umns,  reader  interaction  and  contributions  are  encouraged. 
We  are  pleased  to  welcome  Anthony  aboard  as  a  columnist. 

*  *  * 

Several  months  ago  this  space  contained  discussion  of 
some  issues  involving  the  nature  and  purpose  of  public  do¬ 
main  software.  Recently  we  were  presented  with  another 
situation  which  could  fuel  quite  a  few  ethical  debates.  .  . 

The  situation  could  have  happened  in  any  number  of 
computer  clubs.  A  large  user  group  had  accumulated  a  rath¬ 
er  sizable  library  of  public  domain  software.  Members  were 
allowed  to  copy  disks  at  meetings,  or  they  could  purchase 
disks  from  the  librarian.  In  fact,  the  sale  of  these  disks 
produced  a  substantial  portion  of  the  club’s  income. 

One  day  an  ad  for  public  domain  disks  was  noticed  in  a 
national  periodical.  The  discription  sounded  like  the  club 
library.  Investigation  revealed  that  the  advertised  disks 
were  essentially  the  club  disks  with  the  references  to  the 
club’s  identity  removed.  It  was  further  discovered  that  the 
person  placing  the  ad  was  a  club  member  and  a  member  of 
the  club’s  executive  committee.  There  is  no  indication  that 
he  had  appropriated  any  club  materials  or  equipment. 
Presumably  he  had  simply  made  his  own  set  of  master 
copies  of  the  library  and  was  selling  duplicates  made 
using  his  own  time,  materials,  and  equipment. 


What,  if  anything,  has  he  done  wrong  here?  The  pro¬ 
grams  were  in  the  public  domain,  so  there  is  no  issue  of 
cheating  the  authors  of  the  programs.  There  is  no  indication 
that  he  took  anything  of  material  value  from  the  club.  His 
customers  would  not  be  club  members,  so  he  was  not 
taking  any  income  away  from  the  club.  The  club  had  not 
lost  a  thing  and  the  software  would  get  wider  circulation. 

Even  so,  the  library  was  apparently  collected  and  or¬ 
ganized  through  the  unpaid,  voluntary  efforts  of  the 
members,  and  he  was  using  the  fruits  of  those  efforts  for  his 
own  profit.  Did  he  violate  the  expectations  of  those  mem¬ 
bers?  It  does  not  appear  that  he  added  any  value  to  the 
software  that  he  sold,  and  he  concealed  its  origin.  Were  his 
customers  thereby  deceived  in  any  way? 

The  more  we  look  at  the  situation,  the  more  sides  there 
seem  to  be.  One  central  question  here  involves  one’s  view 
of  the  purpose  of  public  domain  software.  The  other 
members  of  the  executive  committee,  from  their  perspec¬ 
tive,  felt  the  concept  of  Public  Domain  had  been  betrayed. 
The  member  in  question,  however,  felt  that  he  had  done 
nothing  wrong.  In  fact,  he  felt  that  he  was  acting  in  the 
spirit  of  Public  Domain  by  promoting  the  spread  of  the 
disks  at  the  same  price  that  the  club  was  charging. 

This  series  of  events  offers  a  chance  to  examine  some 
fundamental  issues  about  public  domain  software.  Fixing 
guidelines  and  boundaries  in  this  area  can  be  tricky  at  best. 
The  floor  is  open  for  debate.  Readers,  how  do  you  see  it? 

Reynold  Wiggins 
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DR.  DOBB’S  CLINIC 


by  D.  E.  Cortesi,  Resident  Intern 


Intemperate  Editorial  Opinion 

We  received  a  most  formidable  enve¬ 
lope  in  the  mail  early  this  summer  (see 
Figure  1,  page  13).  Brown  manila  paper, 
window,  cryptic  directives  to  “Postmas¬ 
ter”  and  “Recipient”  —  the  sort  of  letter 
that  is  either  going  to  be  an  income  tax 
refund  or  a  draft  notice.  What  was  it?  In¬ 
side  was  a  cheerful  offer  to  let  us  renew 
our  subscription  to  PC  magazine! 

Words  failed  us,  or  at  least  printable 
ones  did.  There  is  presumably  no  law 
against  emulating  the  appearance  of  a 
government  mailing,  but  there  darn  sure 
ought  to  be.  As  it  dawned  on  us  how  we 
had  been  suckered  into  opening  the  enve¬ 
lope,  we  thought  that  this  must  be  the 
most  outrageous  piece  of  commercial 
advertising  we’d  ever  read. 

But  no,  the  contents  of  the  envelope 
actually  displayed  more  sheer  brass  than 
its  exterior:  “Renew  your  subscription 
today  at  current  low  rates  and  avoid  pos¬ 
sible  price  increases  in  coming  months.” 
Price  increases?  Price  increases?  For  PC, 
the  magazine  with  more  advertising  space 
sales  than  any  other  in  the  industry?  Lis¬ 
ten,  they  could  pay  you  to  take  that  mag¬ 
azine  and  still  make  a  handsome  profit ! 
Price  increases  my  rusty  scalpel.  .  .  . 

We  did  not  renew  our  subscription 
to  PC. 

If  I  Were  a  Rich  Person .  .  . 

One  of  our  favorite  recreations  is 
reading  the  ads  in  computer  magazines, 
choosing  the  components  of  our  ideal 
computer  system.  Do  you  do  that?  Grand, 
let’s  indulge  in  a  group  fantasy. 

Here’s  the  scenario.  Your  eccentric 
uncle,  Backus  “Bits”  Naur,  cast  off  this 
mortal  coil  on  June  30th.  He  left  you  a 
bequest  of  $9,999,  but  he  attached  the 
conditions  that  you  must  spend  at  least 
half  of  it  on  a  new  computer  for  your 
personal  use,  and  that  you  must  assemble 
the  system  within  six  months  of  his  death. 
It’s  a  great  opportunity,  but  you  realize 
that  whatever  you  buy  will  have  to  last 
you  for  some  years.  You  will  want  the 
most  quality,  capacity,  and  flexibility  you 
can  get.  On  the  other  hand,  the  less  you 
spend,  the  more  change  you’ll  have  for 
other  things  (like  placating  your  spouse). 

There  is  the  challenge:  how  good  a 
system  can  you  build  for  a  price  between 
$4,998.50  and  $9,999.00,  based  on  com¬ 
ponents  that  you  could  obtain  by  Decem¬ 
ber  31st?  Be  specific  about  makes  and 
prices.  We  will  publish  the  gestalt  results 
early  next  year. 


The  Buffered  Keyboard,  Again 

In  the  May  Clinic  we  told  about  our 
problems  using  an  interrupt-driven,  buf¬ 
fered  keyboard  under  CP/M.  We  made 
one  mistake  and  overlooked  one  obvious 
fix.  The  mistake  was  in  reporting  the  re¬ 
sults  of  tests  under  CP/M  3.0  as  if  they 
were  true  of  CP/M  2.2;  they  weren’t. 
Here’s  the  truth  of  the  matter. 

The  problems  arise  when  you  try  to 
type  ahead  of  the  system.  The  typed 
bytes  accumulate  in  the  BIOS’s  keyboard 
buffer  and  are  ready  whenever  the  system 
wants  them.  However,  under  CP/M  2.2, 
the  BDOS  polls  the  console  frequently  to 
see  if  a  key  has  been  hit.  The  poll  is  done 
prior  to  each  byte  of  console  output,  and 
perhaps  at  other  times.  If  a  key  has  been 
pressed,  the  BDOS  reads  the  byte  and  ex¬ 
amines  it.  If  it  is  a  control-S,  output  to 
the  screen  is  halted  until  another  charac¬ 
ter  is  typed. 

If  the  byte  is  not  a  control-S,  the 
BDOS  tucks  it  away  in  a  one-byte  buffer 
of  its  own,  and  ceases  to  do  the  polling 
during  output  until  a  console  input  re¬ 
quest  has  emptied  that  buffer.  This  is 
why  control-S  won’t  work  unless  it  is  the 
very  first  keystroke  given.  Hit  any  other 
key  and  you  have  filled  the  one-byte  buf¬ 
fer  and  caused  the  poll  to  be  bypassed 
until  the  next  input  request  from  a  pro¬ 
gram.  (Incidentally,  a  program  that  calls 
the  BIOS  directly  for  console  input  will 
never  see  that  BDOS -buffered  byte.) 

We  sometimes  lose  the  leading  byte 
(and  only  the  leading  byte)  of  a  typed- 
ahead  line  under  CP/M  2.2.  The  reason 
for  this  was  explained  by  Allan  Bomber- 
ger.  “Many  programs  do  a  one  byte  read 
to  clear  the  one  byte  buffer  in  the  BDOS 
before  they  return  to  location  zero.  PIP 
does  it.  ASM  does  it.  The  solution  is  to 
begin  lines  with  control-X  while  typing 
ahead.  The  control-X  goes  into  the  BDOS 
buffer  and  stops  the  BDOS  from  polling 
the  console.  If  the  program  reads  one 
byte,  it  reads  the  control-X.  If  a  program 
doesn’t  read  the  control-X,  it  is  processed 
by  the  BDOS  as  ‘erase  line’  and  has  no 
effect  as  the  first  character.” 

Typing  a  control-X  as  the  first  byte 
of  a  typed -ahead  line  works  very  well 
under  CP/M  2.2.  So  does  typing  control- 
U  (suggested  by  L.  Barker)  or  typing  a 
Return  (Nick  Hammond).  Thanks  to  all 
three  for  pointing  out  this  fix. 

One  problem  remains  unfixed  and 
probably  unfixable:  that  some  programs 
take  any  pending  console  input  as  an 
abort  signal.  Some  are  worse  than  others. 


Bomberger  says,  “The  CCP  is  not  nice.  It 
polls  the  console  all  the  time  during  many 
of  its  operations.  It  does  not  buffer  what 
it  reads.  A  patch  to  the  CCP  will  stop  it 
from  polling  all  the  time  during  ERA  and 
DIR  and  TYPE,  etc.,  but  this  means  that 
you  are  unable  to  stop  those  commands 
prematurely.” 

That’s  CP/M  2.2.  When  we  claimed 
that  we  lost  one  typed-ahead  byte  for 
every  byte  of  console  output,  we  were 
reporting  what  happened  under  CP/M  3.0. 
Nick  Hammond  of  Torrens,  Australia 
noticed  the  same  thing.  “CP/M  Plus  eats 
a  character  for  every  character  it  displays. 
The  sequence 

pip  b:  =  a: somethin  CR  stat  b:  CR 
will  eat  the  ‘s’  of  the  stat  command  in 
user  0,  but  the  ‘st’  in  user  1  because  of 
the  extra  prompt  character.  Pipping  a  list 
of  files  clears  the  buffer  since  one  is  swal¬ 
lowed  for  each  character  of  the  filenames 
displayed.” 

How  To  Be  Standard 

Everybody  talks  about  ASCII,  but 
very  few  people  really  understand  it. 
Sure,  it’s  a  “standard”  for  the  encoding 
of  characters  as  binary  values.  But  what  is 
a  standard,  really?  Who  says  it’s  a  stan¬ 
dard,  and  what  does  this  standard  actual¬ 
ly  say? 

Well,  it’s  a  standard  because  the 
American  National  Standards  Institute 
sanctions  it.  And  you,  too,  can  find  out 
what  the  ASCII  standard  really  says  for 
yourself.  There  are  three  standard  docu¬ 
ments  that  define  what  ASCII  is,  and 
they  go  far  beyond  naming  the  patterns 
of  bits  it  uses.  They  are  interesting  techni¬ 
cal  documents  in  their  own  right,  and 
they  should  be  on  the  desk  of  every  re¬ 
sponsible  systems  programmer. 

The  first  document  is  American  Na¬ 
tional  Standard  Code  For  Information 
Interchange  (ANSI  X3.4).  This  20-page 
pamphlet  defines  the  ASCII  code  values 
and  summarizes  their  intended  uses.  Its 
most  interesting  parts  are  its  appendices. 
Appendix  A  is  a  careful  explanation  of 
the  design  tradeoffs  that  were  made  in 
defining  the  code  set.  Did  you  ever  won¬ 
der  what  the  FS,  GS,  RS,  and  US  bytes 
were  for?  Appendix  A  will  tell  you.  Ap¬ 
pendix  B,  “Notes  on  Application,”  is  the 
grabber.  Is  the  CP/M  convention  of  end¬ 
ing  each  line  with  CR,  LF  a  standard  use 
of  ASCII?  Is  it  more  or  less  standard  than 
the  UNIX  convention  of  using  LF  alone? 
You  can  find  out  by  reading  Appendix  B. 
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The  second  document  has  the  un-  few  Clinics  have  had  a  lot  of  stuff  gener-  you  is  an  intractable  problem  will  almost 

lovely  title  of  American  National  Stan-  ated  by  the  Intern.  That’s  because  you  certainly  provoke  multiple,  elegant  solu- 

dard  Code  Extension  Techniques  for  Use  aren’t  contributing!  One  of  these  months  tions  from  the  readership.  Write! 
with  the  7-Bit  Coded  Character  Set  (ANSI  the  mailbag  and  the  Intern’s  mind  are 
X3.41).  This  document  specifies  the  stan-  going  to  come  up  empty  at  the  same 

dard  ways  in  which  ASCII  (a  7-bit  code)  time,  and  there  won’t  be  a  Clinic.  We  need  PBj 

can  be  extended.  There  are  two  dimen-  problems,  discoveries,  bugs,  triumphs, 

sions:  it  can  be  embedded  in  an  8-bit  puzzles,  pitfalls,  gripes  —  anything.  Some 

code;  and  it  can  represent  an  extended  set  of  our  best  topics  have  come  on  postcards 

of  graphic  or  control  symbols.  Or  both,  and  in  hand-written,  one-page  letters, 

since  methods  are  shown  for  implement-  What  to  you  was  a  trivial  discovery  might 

ing  an  indefinite  number  of  graphic  and  save  somebody  else  many  hours;  what  to 

control  sets  using  either  7-bit  or  8 -bit 
codes.  This  is  the  document  that  makes  it 
clear  how  nonstandard  most  personal 
computer  displays  are,  and  reveals  how 
they  could  all  have  been  compatible  while 
retaining  each  vendor’s  unique  graphics. 

The  third  document  is  becoming 
more  interesting  every  day,  as  we  do  more 
and  more  teleprocessing.  It  has  another 
run-on  title:  American  National  Standard 
Procedures  for  the  Use  of  the  Communi¬ 
cation  Control  Characters  In  Data  Com¬ 
munication  Links  (ANSI  X3.28).  This 
book  amounts  to  a  graduate-level  course 
in  telecommunications.  It  specifies  the 
exact  function  of  the  ASCII  control 
characters  when  transferring  data  over  a 
phone  line.  Each  of  them  has  a  function; 
do  you  know  what  they  are?  But  the  best 
part  is  the  many,  many  sample  protocols 
that  are  laid  out  —  complete  with  proce¬ 
dures  for  handling  timeouts,  transmission 
errors,  every  possible  mishap  that  can 
strike  a  phone  line.  Protocols  are  given 
for  both  synchronous  and  asynchronous 
hardware. 

This  is  not  an  easy  book  to  read,  but 
if  you  have  to  design  a  teleprocessing 
system,  it  will  repay  your  efforts  richly. 

We  drew  on  it  to  devise  a  simple  protocol 
for  sending  files  from  a  CP/M  machine  to 
an  IBM  PC  over  a  20-foot  serial  cable;  it 
was  a  great  help.  Incidentally,  did  you 
realize  that  the  XMODEM  protocol  is 
almost  ANSI-standard?  XMODEM  opens 
the  communications  link  by  sending  a 
NAK  from  receiver  to  sender.  Had  Ward 
read  X3.28,  he’d  have  probably  done  it 
by  sending  an  ENQ  from  sender  to  re¬ 
ceiver,  with  a  response  of  ACK  to  begin 
transmission  or  a  NAK  to  say  “try  me 
later.”  That’s  the  function  of  ENQ. 

These  books  are  available  from  the 
American  National  Standards  Institute, 

1430  Broadway,  New  York,  NY  10018. 

Their  prices  are 

X3.4  (ASCII  code)  $  5.00 

X3.41  (code  extensions)  8.00 

X3.28  (communications)  16.00 

There  is  a  handling  charge  of  $5  on  each 
order  totalling  less  than  $50,  and  you 
must  send  a  check  with  the  order.  It’s  a 
worthwhile  investment. 


Pass  The  Hat,  Again 

You  may  have  noticed  that  the  last 
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C/UNIX  PROGRAMMER’S  NOTEBOOK 


by  Anthony  Skjellum 


This  column  will  deal  with  the  C  pro¬ 
gramming  language  and  the  UNIX  operat¬ 
ing  system.  These  two  software  systems 
help  programmers  produce  maintainable 
and  portable  code.  While  C  is  widely  sup¬ 
ported  on  microcomputers  and  clearly 
merits  discussion,  UNIX  is  only  beginning 
to  become  available  and  then  only  on 
more  expensive  microcomputers.  Never¬ 
theless,  as  UNIX  design  concepts  begin 
filtering  down  into  the  more  conventional 
operating  systems,  discussing  UNIX  fea¬ 
tures,  successes,  and  shortcomings  be¬ 
comes  both  interesting  and  worthwhile. 

This  column  will  also  include  discus¬ 
sion  of  software  design  approaches  and 
current  trends.  Specific  features  of  C  and 
UNIX  will  be  discussed,  as  well  as  more 
general  programming  concepts.  This  will 
make  some  of  the  material  presented  here 
pertinent  to  many  types  of  computer  sys¬ 
tems  and  languages. 

Readers  are  invited  to  participate  in 
this  column.  I  hope  that  some  of  the 
topics  will  spur  readers  into  producing 
responses,  new  ideas,  and  even  new  code. 
Since  this  column  will  be  published  bi¬ 
monthly,  readers  will  have  plenty  of  time 
to  respond  to  the  topics  covered  in  any 
given  issue. 

We  start  this  first  column  with  a  dis¬ 
cussion  of  the  layout  of  C  code  and  move 
on  to  a  discussion  of  runtime  libraries  and 
linkage  compatibility  for  several  8080/ 
Z80/8086  compilers.  In  the  next  column, 
we  will  discuss  how  UNIX -type  environ¬ 
ments  tend  to  produce  noninteractive  pro¬ 
grams.  I  look  forward  to  your  responses 
and  suggestions  for  future  topics. 

Layout  of  C  Code 

The  C  language  is  one  of  the  few 
standards  that  apply  to  a  wide  variety  of 
computers.  The  C  Programming  Language, 
by  Kernigham  and  Ritchie,  defines  a  stan¬ 
dard  language  and  runtime  library  and 
also  discusses  differences  in  several  mini¬ 
computer  implementations.  The  book, 
however,  does  not  define  a  standard  for 
the  layout  and  presentation  of  C  code, 
considering  this  a  matter  of  personal  taste. 
After  reading  a  large  number  of  C  pro¬ 
grams  from  many  sources,  I  have  decided 
that  programmers  pay  too  little  attention 
to  this  aspect  of  C  programming.  In  the 
following  paragraphs,  I  will  explain  the 
problem  as  I  see  it,  suggest  a  standard  for 
C  code  layout,  and  propose  a  possible 
solution. 

Whenever  I  receive  a  new  piece  of  C 
code,  I  always  check  to  see  how  the  pro¬ 


grammar  has  presented  the  code.  A  clear 
presentation  with  many  comments  and  an 
uncluttered  look  is  important  for  main¬ 
taining  such  code  and  for  aiding  other 
programmers  who  must  understand  it. 
More  often  than  not,  the  code  looks 
something  like  the  following: 

main(  ){printf(“Hello  world\n”); 

\ 

In  this  case  the  programmer  hasn’t  for¬ 
matted  the  code  properly.  This  makes  it 
difficult  to  follow  the  inherent  block 
structure  of  the  language  The  cluttered 
look  that  results  from  improper  indenta¬ 
tion  is  often  accompanied  by  a  paucity  of 
comments.  The  result  is  code  that  is  hard 
to  understand,  improve,  or  debug. 

The  style  presented  in  Kernigham 
and  Ritchie  is  consistent  but  not  optimal, 
since  it  does  not  present  blocks  and  block 
nesting  in  the  clearest  way  possible.  For 
example,  an  if .  .  .  else  loop  would  appear 
as  in  Figure  1  (page  17).  Using  the  same 
fragment,  my  preference  is  for  the  format 
shown  in  Figure  2  (page  17).  In  this  for¬ 
mat,  eight-space  (standard)  tabs  are  used 
for  indentation  (as  opposed  to  the  six- 
space  indentation  used  by  the  book). 
Braces  are  almost  always  on  their  own 
lines,  and  the  lowest  level  braces  appear 
at  the  left  margin.  Braces  indicate  the 
nesting  level  of  the  expression  that  invoked 
them,  and  their  contents  themselves  are 
indented  an  additional  level.  Only  one 
statement  is  placed  on  a  line,  and  com¬ 
ments  are  added  liberally  to  make  the 
code  more  readable.  Finally,  the  space 
used  by  Kernigham  and  Ritchie  between 
keywords  and  their  parenthetical  expres¬ 
sions  is  omitted. 

This  example  illustrates  the  layout 
standard  I  am  proposing,  which  is  sum¬ 
marized  in  Table  I  (page  18).  My  purpose 
in  proposing  this  standard  is  to  induce  C 
programmers  to  think  more  carefully 
about  the  layout  and  presentation  of 
their  C  code.  Clearly,  there  is  more  to 
programming  than  the  layout  of  the  code. 
The  data  structures  used  and  the  program 
structure  are  crucial  in  producing  a  good 
piece  of  software.  However,  without  good 
layout  the  best  program  may  be  difficult 
to  understand,  maintain,  or  improve.  I 
invite  reader  response  to  the  layout  pro¬ 
posal. 

A  Possible  Solution 

I  expect  that  even  if  The  C  Program¬ 
ming  Language  described  a  layout  stan¬ 
dard,  some  programmers  would  deviate 


from  it.  In  order  to  provide  programmers 
with  flexible  code  layouts,  C  beautifiers 
can  be  created.  Such  programs  take  C 
code  as  input  and,  by  adding/removing 
white  space  characters,  reformat  the  C 
code  to  some  individual  layout  specifica¬ 
tion.  This  allows  each  programmer  to  dis¬ 
tribute  code  in  a  standard  layout,  while 
using  his  or  her  individual  layout  for  local 
copies  of  the  code. 

Beautifiers  already  exist.  For  exam¬ 
ple,  Berkeley  UNIX  has  a  beautifier  called 
CB.  This  program  is  fairly  simple-minded 
but  will  convert  unformatted  C  code  that 
uses  a  minimum  amount  of  white  space 
into  the  Kernigham  and  Ritchie-type 
layout.  More  ambitious  beautifiers  can  be 
created;  readers  who  create  their  own 
beautifiers  are  invited  to  submit  their 
code  for  publication  in  this  column. 

Runtime  Libraries 

The  C  Programming  Language  defines 
a  standard  runtime  library  for  C.  Some  of 
the  features  provided  are  only  feasible 
under  UNIX.  Thus,  for  CP/M,  CP/M-86, 
and  MS-DOS  implementations,  only  part 
of  the  runtime  library  can  be  supported. 
Yet  some  C  compilers  do  not  provide  a 
compatible  subset  library.  The  result  is 
code  that  cannot  be  easily  transported 
from  compiler  to  compiler  or  from  ma¬ 
chine  to  machine.  Such  compilers  negate 
one  of  the  primary  purposes  of  the  C  pro¬ 
gramming  language:  portability. 

The  BDS  C  compiler  is  one  such  soft¬ 
ware  product.  It  is  an  excellent  subset 
compiler,  but  its  runtime  library  is  incom¬ 
patible  with  the  standard.  After  using 
BDS  C  for  more  than  three  years,  I  have 
accumulated  a  significant  number  of  use¬ 
ful  subroutines  and  programs.  Unfortu¬ 
nately,  some  of  this  software  depends 
heavily  on  the  BDS  C  runtime  library. 
This  code  will  require  a  great  deal  of 
work  before  it  can  be  used  with  another 
compiler.  Be  aware  of  this  pitfall  and  be 
prepared  to  live  with  the  consequences 
if  you  choose  a  compiler  with  a  non¬ 
standard  runtime  library. 

BDS  C  is  not  the  only  compiler 
whose  runtime  library  is  nonstandard. 
The  Whitesmith  C  compilers  are  another. 
Since  Whitesmith  compilers  are  available 
for  many  different  environments,  how¬ 
ever,  portability  between  Whitesmith 
compilers  is  immediate.  Nevertheless,  my 
preference  is  for  code  written  for  use 
with  the  standard  library  and  for  com¬ 
pilers  that  support  that  library  in  full  or 
subset  form. 
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Link  Formats 

Besides  incompatible  runtime  librar¬ 
ies,  there  is  the  question  of  subroutine 
linkage  and  linkage  editor  formats.  Once 
again  BDS  C  is  nonstandard;  that  is,  it 
uses  its  own  linker  instead  of  conforming 
to  the  Microsoft  .REL  format.  (Some 
8080/ Z80  compilers  do  support  the  stan¬ 
dard,  such  as  the  Q/C  compiler  from  The 
Code  Works.)  Compatibility  with  the 
.REL  format  is  a  considerable  blessing  if 
you  plan  to  link  other  software  to  your  C 
programs. 

The  lack  of  linkage  compatibility  is 
not  limited  to  the  CP/M-80  world.  A 
wide  variety  of  C  compilers  sold  for  MS- 
DOS  and  CP/M-86  also  fail  to  use  the 
appropriate  standard.  Most  notably,  Com¬ 
puter  Innovations’  excellent  C86  compil¬ 
er  uses  its  own  internal  format,  which 
makes  it  impossible  to  use  C86  to  pro¬ 
duce  subroutines  for  other  compiled  lan¬ 
guages  under  MS-DOS  or  CP/M-86.  For¬ 
tunately,  the  MANX  AZTEC  compilers 
can  be  used  as  an  option  to  produce  Mi¬ 
crosoft  format  object  code. 

The  reasons  for  linkage  incompati¬ 
bility  are  probably  manifold.  The  usual 
response  from  the  companies  producing 
the  incompatible  products  is  that  they 
prefer  their  own  format  to  Microsoft’s. 
Why  is  this?  I  suppose  they  assume  that 
programmers  don’t  care  about  standards 
or  don’t  think  that  their  end  users  would 
find  a  compatible  linkage  format  useful. 
In  any  case,  be  aware  of  the  linkage  for¬ 
mat  used  by  the  C  compilers  you  select. 


Conclusion 

This  column  is  intended  to  be  a 
forum  for  reader  discussion  as  much  as  it 
is  a  resource.  This  first  installment  has 
examined  a  potential  C  code  layout  stan¬ 
dard,  and  has  discussed  incompatibility  in 
C  object  code  formats  and  runtime  librar¬ 
ies.  Discussion  and  comment  on  these  and 
other  topics  are  welcome.  Questions,  use¬ 
ful  programs,  problems,  insights,  and 
suggestions  are  all  encouraged.  I  look 
forward  to  hearing  from  you. 

Next  time,  we’ll  begin  discussing  how 
UNIX -like  environments  tend  to  produce 
noninteractive  code .... 


(Table  I  begins  on  page  1 8) 
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Table  I 

Proposed  Standard  for  C  Code  Layout 


1.  Standard  tabs  are  used  for  program  indentation. 

a.  Four-space  tabs  may  be  used,  if  desired,  after  column 
56.  This  is  permitted  in  order  to  prevent  line  wrap  on 
80-column  displays. 

2.  A  brace  is  generally  on  a  line  by  itself. 

a.  The  lowest  level  braces  appear  on  the  left  margin. 

b.  Comments  may  appear  on  lines  containing  a  brace, 
but  only  after  the  brace. 

c.  Braces  are  indented  to  the  same  depth  as  the  state¬ 
ment  that  invoked  the  block  they  frame. 

d.  In  variable  initializations,  the  opening  brace  may  be 
placed  on  the  same  line  as  the  equal  sign,  but  the 
closing  brace  must  have  the  same  indentation  as  the 
opening  one. 

e.  In  general,  no  statements  may  appear  on  the  same 
line  as  a  brace. 

3.  A  block  begins  with  a  left  brace  and  ends  with  a  right 

brace.  Its  contents  are  indented  an  extra  level  to  indicate 

the  nesting  depth. 

a.  Whenever  a  block  is  longer  than  24  lines  (a  standard 
CRT  page),  a  comment  should  follow  the  closing 
brace  to  indicate  the  block  that  the  brace  closes. 

i.  This  applies  to  whole  functions  as  well  as  regular 
blocks. 

ii.  This  rule  should  also  be  applied  to  shorter  blocks 
when  block  nesting  makes  the  code  complex  and 
these  comments  improve  the  readability. 

b.  The  opening  and  closing  braces  of  a  block  are  always 
indented  identically. 

c.  The  case/default  labels  of  a  switch  statement  are  al¬ 
ways  indented  a  level,  like  statements  in  a  block.  The 
statements  that  follow  these  labels  are  always  indented 
an  extra  level  to  improve  readability. 

d.  Regular  labels  (destinations  for  GOTO's)  are  always 
placed  at  the  left  margin,  regardless  of  nesting  depth. 

e.  When  a  null  block  is  used  (e.g.,"{  }''),  it  may  appear  on 
the  same  line  as  statements  (e.g.,  do  •[}  while(expr); ). 

f.  If  a  single  statement  is  used  instead  of  a  block,  it  is 
indented  a  single  level,  just  as  if  it  were  surrounded 
by  braces. 

i.  Null  statements  (i.e.,  just  a  are  indented  in 
the  same  way  as  regular  statements. 

4.  White  space  is  added  in  expressions  and  assignments  to 

improve  readability. 

a.  Relational  operators  are  delimited  by  single  spaces. 

b.  Equal  signs  are  delimited  by  single  spaces. 

c.  Unary  operators  are  not  separated  by  space  from 
their  operands. 

d.  Parentheses  are  added  to  improve  readability  in  com¬ 
plex  expressions,  even  if  they  are  not  required  to  pro¬ 
duce  correct  evaluation. 

i.  A  return  statement  always  has  a  set  of  parentheses 
surrounding  its  expression. 
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e.  No  white  space  character  is  placed  between  function 
names  and  their  parenthesized  argument  list. 

f.  No  white  space  character  is  placed  between  a  key¬ 
word  (e.g.,  if)  and  its  parenthesized  argument. 

5.  Comments  are  added  liberally  to  make  the  program  read 
easily. 

a.  If  a  comment  requires  more  than  one  line,  the  start/ 
end  comment  tokens  are  placed  on  lines  containing 
no  comment  text.  In  this  case,  the  start/end  tokens 
are  indented  identically. 

b.  If  a  comment  fits  on  a  single  line,  the  start/end  to¬ 
kens  must  also  be  placed  on  that  line. 

6.  Variables  are  always  declared,  even  if  your  version  of  C 
has  a  default  type.  Always  explain  the  purpose  of  your 
variables. 

a.  Declare  the  variables  in  logical  groups  and  include  a 
comment  on  the  same  line  as  the  declaration  to  de¬ 
scribe  the  function(s)  of  the  variable(s). 

b.  Avoid  numerous  declarations  on  a  single  line. 

c.  Explain  complex  pointer  declarations. 

d.  Variable  names  are  always  lower  case  only. 

e.  External  variable  declarations  may  be  indented  a  sin¬ 
gle  level  for  greater  readability. 

7.  Constants  created  with  #define  are  always  upper  case. 
Macros  created  with  #define  may  be  upper  or  lower  case. 

a.  As  with  variables,  constants  should  have  comments 
to  explain  their  purpose. 

b.  Macros  should  be  explained  via  comments  to  avoid 
misunderstandings  about  their  uses.  This  is  especially 
important  since  macros  tend  to  be  cryptic. 

c.  Restrict  #define  statements  to  the  beginning  of  code 
files  (i.e.,  before  the  first  function).  This  avoids  the 
potential  for  redefinition  and  other  confusion. 

8.  Other  items. 

a.  The  else  .  .  if(expr)  construct  is  placed  on  a  single  line 
as  if  it  were  a  single  keyword. 

b.  Function  names  are  always  lower  case. 

9.  Portability  considerations. 

a.  When  using  a  nonstandard  C  feature,  always  prepare  a 
portable  alternative  that  may  be  selected  via  condi¬ 
tional  compilation. 

b.  Indicate  any  subtle  uses  of  sign  extension  and  type 
conversions  made  by  your  program  or  your  specific 
compiler. 

c.  Indicate  any  deviations  in  the  way  your  compiler  han¬ 
dles  pointer  arithmetic. 

d.  Include  the  ampersand  operator  ("&")  when  you  pass 
pointers  to  structures,  even  if  your  compiler  doesn't 
require  it.  Someone  else's  compiler  may  support  pass¬ 
ing  structures. 

e.  Indicate  any  deviations  of  your  runtime  library  from 
the  standard. 

f.  Indicate  any  deviation  in  the  (argc,argv)  command 
line  conventions  made  by  your  compiler. 
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UNIX  to  CPIM 

Floppy  Disk  File  Conversion 


The  increasing  availability  of  good, 
moderate-cost  C  compilers  for  use 
on  microprocessor  systems  has  gen¬ 
erated  significant  interest  in  the  C  language 
among  microprocessor  system  users.  Ron 
Cain’s  Small- C  compiler  with  its  improve¬ 
ments  (see  J.  E.  Hendrix’s  Small  C  Com¬ 
piler,  v.  2,  DDJ  Nos.  74,  75  )  and  the  BDS 
C  compiler  have  spawned  a  large  C  users 
group  among  CP/M  users.  The  C  language 
was  specifically  developed  for  the  UNIX 
operating  system,  and  there  is  a  large 
amount  of  software  written  in  C  available 
on  UNIX  systems.  Since  the  file  structures 
of  UNIX  and  CP/M  files  are  worlds  apart, 
there  is  no  direct  way  to  read  UNIX  C 
source  files  under  CP/M.  The  purpose  of 
this  article  is  to  describe  the  structure  of 
UNIX  files  and  a  program  written  by  the 
author  to  read  UNIX  floppy  disks  under 
CP/M. 

Examining  UNIX  Files  Under  CP/M 
The  Bell  Labs  UNIX  programming 
manual  describes  the  basic  structure  of 
the  UNIX  file  system.  The  detailed  infor¬ 
mation  listed  in  the  next  section  was 
actually  obtained  by  comparing  UNIX 
floppy  disk  dumps  with  the  information 
in  the  UNIX  manuals.  A  program  provided 
with  the  ZMAC  macro  assembler  called 
DUMPDSK  significantly  simplified  the 
process  and  was  also  used  as  a  pattern  for 
writing  UNIXTCPM.  DUMPDSK  is  an 
example  program  on  the  use  of  ZMAC 
and  the  associated  ZSUBL1B  subroutine 
library.  DUMPDSK  dumps  a  SSSD  8-inch 
IBM  3740  format  floppy  disk  starting  at 
track  0,  sector  1 ,  using  an  interleave  fac¬ 
tor  of  6.  (Most  DEC  floppy  disk  drive 
systems  used  with  UNIX  use  the  IBM 
3740  format  and  an  interleave  factor  of 
6.)  The  UNIXTCPM  program  which  ac¬ 
companies  this  article  (Listing  One,  page 
24)  will  only  work  with  UNIX  files  writ¬ 
ten  by  such  drives. 
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UNIX  Files 

The  UNIX  operating  system  provides 
a  hierarchical  file  system,  which  simply 
means  that  file  directories  and  files  are 
organized  in  a  tree  structure.  The  struc¬ 
ture  is  really  quite  simple  and  all  files, 
including  directories,  are  viewed  simply 
as  a  one-dimensional  array  of  bvtes.  A 
disk  is  viewed  as  a  conically  random  access 
device  with  data  partitioned  into  512-byte 
blocks.  Thus  the  basic  unit  of  disk  storage 
is  a  block  of  5  12  bytes. 

Blocks  are  numbered  sequentially 
starting  at  block  0,  which  comprises  the 
first  512  bytes  on  a  disk.  Block  0  is  not 
used  by  the  file  system  and  is  reserved  for 
system  booting  operations.  The  second 
block,  or  block  1,  is  called  the  “super 
block.”  This  block  contains  the  capacity 
of  the  file  device,  available  free  blocks, 
and  other  information  as  described  in 
Table  I  (page  22). 

The  next  block  in  the  UNIX  file  sys¬ 
tem,  block  2,  is  the  beginning  of  a  struc¬ 
ture  called  “ I -list.”  I -list  is  a  sequence  of 
structures  that  relates  a  given  file  to  the 
blocks  comprising  the  file  on  the  disk. 
Each  successive  64  bytes  in  I -list  holds  a 
file  allocation  descriptor,  one  per  file, 
called  an  “inode.”  The  inode  is  the  basic 
and  most  important  file  structure  element 
in  the  UNIX  file  system.  The  structure  of 
each  inode  is  described  in  Table  II  (page 
22). 

The  UNIX  file  system  device  format 
just  described  is  depicted  in  Figure  1 
(page  23).  I-list  runs  from  block  2  to  isize, 
which  is  the  first  two  bytes  in  the  super 
block.  Isize  thus  designates  the  start  of 
the  data  area  and  the  end  of  I-list.  Each 
inode  is  assigned  a  number  called  the 
I-number.  Thus,  I-number  1  designates 
inode  1,  or  the  first  64  bytes  of  I-list;  I- 
number  2  designates  the  second  64  bytes 
of  I-list,  etc.  By  convention,  I-number  2 
is  the  inode  for  the  root  directory  blocks 
in  the  file  system  and  I-number  1  is,  for 
all  practical  purposes,  unused. 

Directory  files  in  UNIX  are  exactly 
like  ordinary  files  except  that  they  can¬ 
not  be  written  into  by  a  user.  The  mode 
byte  in  the  inode  of  a  file  indicates  the 
type  of  file  involved.  Each  directory 
block  has  space  for  32  16 -byte  directory 
entries.  The  first  and  second  bytes  of 
each  entry  are  the  I-number  for  the  file. 
The  remaining  14  bytes  are  the  name  of 
the  file  left  adjusted  in  the  field.  The  first 
directory  entry  in  the  root  directory  is 
for  the  root  directory  block  itself  and  the 


second  is  for  the  parent  directory.  The 
third  entry  is  for  the  first  actual  file.  The 
UNIX  file  system  just  described  is  shown 
in  Figure  2  (page  23 ). 

Accessing  a  file  on  a  UNIX  disk  may 
be  accomplished  by  the  following  se¬ 
quence  of  operations: 

(1)  Read  address  1  of  inode  number  2  to 
obtain  the  block  number  of  the  root 
directory.  In  the  case  of  a  floppy  disk 
with  an  IBM  3740  format,  this  would 
be  CP/M  track  0,  sector  23,  bytes  4C, 
4D,  and  4F.  If  the  root  directory  is 
filled,  addr  2  of  inode  2  points  to  the 
next  directory  block,  etc. 

(2)  Read  the  root  directory  block  desig¬ 
nated  above.  The  root  directory  on  a 
floppy  disk  generally  is  in  block  24, 
starting  in  CP/M  track  3,  sector  6. 

(3)  Locate  the  desired  file  name  in  the 
directory. 

(4)  Pick  up  the  I-number  for  the  file 
from  the  first  two  bytes  of  the  direc¬ 
tory  entry. 

(5)  Locate  the  inode  for  the  file.  I-number 
1  corresponds  to  the  first  64  bytes  of 
CP/M  track  0,  sector  23,  I-number  2 
to  the  second  64  bytes.  I-number  3 
corresponds  to  the  first  half  of  CP/M 
track  0,  sector  3,  etc. 

(6)  Read  the  file  blocks  assigned  to  the 
file  starting  in  inode  byte  C.  Each 
block  address  is  three  bytes  long  and 
the  first  ten  blocks  are  for  directly 
addressed  file  blocks.  The  last  three 
addr  values  are  for  indirect  pointers, 
as  shown  in  Figure  3  (page  23) 

(7)  Read  the  blocks  assigned  to  the  file. 
In  the  event  the  file  consists  of  more 
than  ten  blocks,  address  11  is  the 
block  number  of  an  array  of  pointers 
to  the  next  128  blocks  in  the  file. 
Each  block  number  is  four  bytes  long 
in  the  pointer  block. 


UNIXTCPM  Program  Design 

The  UNIXTCPM  program  performs 
the  following  listed  set  of  operations: 

(1)  Command  Line  Input 
UNIXTCPM  filename. ext  $081$ 

Filename  _ ^  i 

I-number  for  file _ I 

(2)  Determine  Track  and  Sector  of  Inode 
SQSECT  =  Sequential  Sector 

Number  =  (I-number  1  )/2  +  8 
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TRACK  =  Integer  portion  of 
SQSECT/26 

SCTRANN  =  Position  of  sector  in 
Sector  Translation  Table 
SCTRANN  =  Remainder  of 
SQSECT/26 

(3)  Read  Inode  into  INDBUF 

If  the  I-number  is  odd,  inode  is  in 
the  first  half  of  the  sector;  if  even, 
then  it  is  in  the  second  half. 

(4)  Check  inode  11  at  location  2C,  2D, 
and  2E  for  indirect  block.  If  address 
1 1  is  not  zero,  the  program  reads  the 
pointer  block  specified  by  address  1 1 
into  INDBUFX.  This  program  does 
not  consider  second  order  indirection, 
and  thus  is  limited  to  files  of  70K 
bytes  or  less. 

(5)  Read  a  specified  file  from  the  UNIX 
disk  in  unit  B  and  write  a  CP/M  file 
on  unit  A. 

UNIXTCPM  Program  Source  Listing 

The  UNIXTCPM  program  was  writ¬ 
ten  in  Z80  assembly  language  using  the 
ZMAC  macro  assembler  and  the  ZSUB- 
LIB  subroutine  library  provided  with  this 
product.  The  resultant  REL  file  was  then 
linked  to  form  a  COM  file  using  ZLINK. 
The  program  was  tested  using  three  dif¬ 
ferent  floppy  disks  with  a  different  set  of 
files  on  each.  The  files  were  created  using 
UNIX  version  7  and  UNIXTCPM  was  able 
to  read  all  of  them.  The  source  code  file 
is  given  in  Listing  One  on  page  24.  In¬ 
cluded  with  the  unixtcpm  program  is 
NLFILTER.COM  (Listing  Two,  page  37), 
which  changes  the  UNIX  newline  to  a 
CR-LF  in  the  CP/M  file. 


(Listings  begin  on  page  24) 


Field  Name 

Bytes 

Function 

isize 

2 

Block  Num  at  End  inode  +  1  =  First  Data  Block 

fsize 

4 

Size  of  entire  disk  in  blocks 

nfree 

2 

Pointer  to  last  allocated  block  in  ifree  array 

free 

4  x  50 

Array  of  50  pointers  to  free  blocks 

ninode 

2 

Number  of  free  Inumbers  to  inode  array 

inode 

2  x  100  +  2 

Array  of  100  pointers  to  inodes  in  1  -list 

flock 

1 

Lock  during  free  list  manipulation 

ilock 

1 

Lock  during  1  -  list  manipulation 

fmod 

1 

Super  block  mod  flag 

ronly 

1 

Read  only  flag 

time 

4 

Time  super  block  last  mod 

tfree 

2 

Total  free  inodes 

m 

2 

Interleave  factor  1 

n 

2 

Interleave  factor  2 

fname 

6 

File  system  name 

fpack 

6 

File  system  pack  name 

Table  1 

Super  Block  Structure 

Field  Name 

Bytes 

Function 

mode 

2 

Type  of  file 

nlink 

2 

Number  of  Dir  entries  for  this  inode 

uid 

2 

Owner  I.D. 

gid 

2 

Group  I.D. 

size 

4 

Number  of  bytes  in  file 

addr 

13x3  +  1 

Array  of  13  3-byte  block  numbers  assigned  to 
file,  first  10  direct,  last  3  indirect 

atime 

4 

Time  last  accessed 

mtime 

4 

Time  last  modified 

ctime 

4 

Time  created 

Table  II 

Inode  Structure 

22 


Circle  no.  32  on  reader  service  card. 
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FILE  SYSTEM  DEVICE  FORMAT 
Each  block  is  512  bytes. 

block  0  I  UNUSI 


block  1 
block  2 

block  M 
block  M  +  1 

• 

block  N 


UNUSED 
SUPER  BLOCK 


DATA 


i 


FILE  SYSTEM  HIERARCHY 

directory 

inode 


directory 


file  (data) 


Figure  1. 


Figure  2. 


DATA  BLOCK 
ADDRESS 


DIRECT 


BYTES 


512  X  10 


SINGLE 

INDIRECT 


DOUBLE 

INDIRECT 


TRIPLE 

INDIRECT 


indirect  block 

1 28  pointers 

indirect  block 

1 28  pointers 

indirect  block 
128  pointers 

- ► 

indirect  block 
1 28  pointers 


indirect  block 
128  pointers 


indirect  block 
1 28  pointers 


128  X  512 


1282 X  512 


1283  X  512 


Figure  3. 
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UNIX  to  CP/M 

Listing  One 


(Text  begins  on  page  20) 


( 0 1 00 ) 
C 36 SO 4 


0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 
0009 
00 1 0 
00 1 1 
0012 
0013 
0014 
00 1  5 
00 1 6 
0017 
00 1 8 
00 1  9 
0020 
0021 
0022 
0023 
0024 
0025 
0026 
0027 
0028 
0029 
0030 
003 1 
0032 
0033 
0034 
0035 
0036 
0037 
0038 
0039 
0040 
004 1 


0 1 03 

( OO 50 ) 

0042 

0043 

0044 

0045 

0153 

ODOA 

0046 

0 155 

3E3E2055 

4E495820 

746F2043 

5 0 2 F  4  D  2  O 

0047 

0 1 65 

46696C65 

20547261 

6E736665 

7  ci  yl'U  oL  SL- 

0048 

0175 

0D0A24 

0049 

0050 

0 1 78 

ODOA 

0051 

0 .1 7  A 

2A2A2045 

0052 

#**#**#*#**#********************tf*********  ************ 
UNIXTCPM  **UNIX  FILE  TO  CP/M  FILE  TRANSFER** 

This  pro  s  ram  assumes  that  UNI  XTlF'M.  COM  is 
on  disk  unit  A  and  that  the  UNIX  disk  is 
is  in  dive  unit  EL  The  CP/M  equivalent  of 
the  specified  UNIX  file  will  be  on  unit  A. 
UNIXTCPM  uses  the  ZSUBLIB  routine  GETSECT 
tnat  eiTiPlovs  direct  BIOS  calls  to  read  a 
single  sector.  This  program  assumes  an 
interleave  factor  of  6  for  the  UNIX  disk. 

Command  Li  ne=UNI  XTCF'M  f  i  1  ename .  ext  $XXX$<.RET_> 
where  xxx  -  UNIX  file  I  number. 

Use  OUMPDSK  on  the  UNIX  floppy  disk  to 
determine  the  I  number  for  the  UNIX  file 
t  o  b  e  transfer  e  d  t  o  C  P / M . 

The  message  "Fatal  Error"  will  be  displayed 
and  UNIXTCPM  will  abort  if  a  bad  I  number 
or  bad  track  and  sector  numbers  a  produced. 

UNIX  newline  in  CP/M  file  must  be  changed 
to  CR  LF  using  program  NLFILTER.COM 
****************************************************** 

— ZSUBLIB  ROUTINES  USED  BY  UNIXTCPM — 

EXT  FCB01 , FNTFCB,  CREATE » CLOSE?  DIV16 

EXT  OPEN , SETBUFF , CONCRLF ,  ADCTB 1 N 

EXT  GETSECT, SELECT, PRNTFN, PUTMC 

EXT  WRTBUF1 ,  SCTBUF1. 


uRG 

BEL*  1 N  >JP 


0 1 00  H 
START 


?  SET  PRuuRAM  RE LA i  I VE 
;  NORMAL.  PGM  ORG 


‘  —  ST  A  U K  7  ME  y  y  A  E  y  7  B  i J  F  F  E  R  y  ?  AN  D  PARA  h  E  i  E  R  S  7  0  R  A  G  E  - 

7  ■*“  —  —  -  •  —  - 

5  —  R  E  8  E  R  V  E  STAC  K  S  F'AuE — 

DEFS  SO 

STACK: 

7 

5  — SIGNON  MESSAGE 
S I G  N  ON  D  E  F  B  O  D  H  ?  U  A  FI 

DEFB  "'»  UNIX  to  CP/M 


File  I  r a nsfe r 


DEFB  ODH  7  OAH ,  ■"  $ 

-EXIT  MESSAGE — 

rMSG  DEFB  ODH  >  OAH 

DEFB  ■' **  End  of  Trans' 


6E64206F 


(Continued  on  page  26) 
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UNIX  to  CPIM  (Listing  continued,  text  begins  on  page  20) 

Listing  One 


6620547; 

616E73 


0 1 89 

66657220 

2A2A0D0A 

0053 

DEFB 

ter 

0191 

24 

0054 

DEFB 

•"  $  ■" 

0055 

? — FILE  NAME 

MESSAGE 

0192 

ODOA 

0056 

MSG1  DEFB 

ODH,  i 

0194 

54686520 

0057 

DEFB 

-The 

46696C65 

20626569 

6E6720 

01 A3  7472616E 
73666572 
65642069 
732020 
01B2  24 

01153  ODOA 
01B5  46617461 

6C204572 
726F72 
01  CO  0D0A24 


01 C A  01070013 
1 9050B 

0101  11170309 

OF 1502 

0108  08 OE 1 4 1 A 

06 OC 1 2 

01 OF  1 8040 A 1 0 
1 600 


0 1 E5  00 
01E6  00 

01E7  00 

01E8  <0080) 

0268  <  0200 ) 


her-  ,  OOH,  OAH 


t r a n s f e r <? d  is 


0059  DEFB  ■" * 

0060  5  — ERROR  MESSAGE- 

0061  MSG 2  DEFB  OOH, OAH 

0062  DEFB  -'Fatal  Error 


0063 

0064 

0065 


DEFB  ODH, OAH,  ' 
5 

; — BINARY  I  NUMBER 


01C3 

0000 

0066 

INUM 

DEFB 

OOH , OOH 

0067 

5 

0068 

; — THREE 

DIGIT  ASCII  UNIX 

01C5 

00 

0069 

D I G 1 

DEFB 

OOH 

01C6 

00 

0070 

D I G2 

DEFB 

OOH 

01C7 

00 

0071 

DIG3 

DEFB 

OOH 

01C8 

00 

0072 

DEND 

DEFB 

OOH 

0073 

7 

0074 

! — POINTER  TO 

POSITION  IN 

01 C  9 

00 

0075 

SCTPTR 

DEFB 

OOH 

0076 

? 

5  EXTRA  0  FOR  L.D  HLUNUM 


0077 

0078 

0079 

0080 

008 1 

0082 

0083 

0084 

0085 

0086 

0087 

0088 

0089 

0090 

0091 

0092 

0093 

0094 

0095 

0096 


SECTOR  TRANSLATION  TABLE — 

TRAN  DEFB  01,07,013,019,025,05,011 


SECTRAN  DEFB 
DEFB 
DEFB 
DEFB 


0 1 7 , 023 , 03 , 09 , 0 1 5 , 02 1 , 02 
08 , 0 1 4 , 020 , 026 , 06 ,  0 1 2 , 0 1 8 
024 ,  04 , 0 1 0 , 0 1 6 , 022 , 00 


; — TRACK  NUMBER — 

TRACK  DEFB  OOH 

; — SECTOR  NUMBER — 

SECT  DEFB  OOH 

5 

; — INDIRECT  POINTER  BLOCK  SWITCH- 
INDSW  DEFB  OOH 


; — BUFFER  FOR  inode  — 
INDBUF  DEFS  0128 


;ONE  SECTOR 


5 — BUFFER  FOR  1ST  INDIRECT  POINTER  BLOCK 
INDBUFX  DEFS  0512  ;4  SECTORS 


(Continued  on  page  28) 
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0097 

7  " . " .  '  1 . 

7 

0098 

?  **  ACTUAL 

PROGRAM  STARTING  POINT  **  ; 

0099 

7 

7 

0100 

; 

0468 

315301 

0 1 0 1 

START  LD 

SP, STACK  ?  SET  STACK  POINTER 

0 1 02 

; — DO  SIGN ON— 

- 

o46*B 

1 1 530 1 

0103 

LD 

DE , S I GNON 

046E 

CD 00 00# 

0104 

CALL 

PUTMC 

0 1 05 

; — SELECT  DR I 

VE  A — 

0471 

AF 

0 1 06 

XOR 

A 

0472 

CD 000 04 

0107 

CALL 

SELECT 

0 1 08 

; — USE  FNTFCB 

1 U  GET  FILE  NAME  FRuM  COMMAND  LINE  — 

0475 

1 1 0000# 

0109 

L.D 

DE.FCBOl 

O47o 

2 1 5COO 

0 1 1 0 

LD 

HL ,  05 CH  ; COMMAND  LINE 

0478 

CD 00 00# 

01 1 1 

CALL 

FNTFCB 

0 1 1 2 

; — PRINT  FILE 

NAME  INFO — 

04  7E 

1 1 920 1 

0113 

LD 

DE, MSG1 

048 1 

CD 0000# 

0114 

CALL 

PUTMC 

0484 

1 1 0000# 

0115 

LD 

DE, FCB01 

0487 

CD 0000# 

0 1 1 6 

CALL 

F’RNTFN 

048 A 

CD0000# 

0117 

CALL 

CONCRLF  5  CON  NEWLINE 

01 18 

; — CREATE  CP/M  FILE — 

01 19 

; — NOTE:  NO  CHECK  IS  MADE  FOR  DUPLICATE 

0120 

;  FILE 

BY  THIS  NAME  ON  UNIT  A — 

048D 

1 10000# 

0 1 2 1 

LD 

DE.FCBOl 

0490 

CDOOOO# 

0 1 22 

CALL 

CREATE 

0123 

: — GET  I  NUMBER  FROM  COMMAND  LINE — 

0493 

CD2605 

0124 

CALL 

GETINUM 

0125 

; — CONVERT  I 

NUM  TO  INODE  TRACK  AND  SCTT — 

0496 

CD5E05 

0126 

CALL 

CNV I NUM 

0127 

; — GET  UNIX  FILE  inode  from  disk  B — 

0499 

1  IE 801 

0123 

LD 

DE, INDBUF 

0 1 29 

5  —  READ  i  n  c«  d & 

SECTOR  INTO  INDBUF — 

0130 

; — Note:  CNVINUM  sets  track  and  sector - 

049C 

CD 84 05 

0 1 3 1 

CALL 

RD 1 SECT  ; READ  ONE  SECTOR 

0 1 32 

7  —  L-HE  U  K  -a.  d  d  r 

11  for  1st  INDIRECT  BLOCK — 

049F 

3AC30 1 

0133 

LD 

A,  <1 NUM)  ; GET  I  number 

U4m.'l' 

E601 

0134 

AND 

0 1 H  ;  C K  f  o r  o d d  or  e v e n 

04  A  4 

2 A 1 302 

0 1 35 

LD 

HL ,  ( I NDBUF+02BH )  iaddr  11  o d  d 

04  A  7 

ED5B5302 

0 136 

LD 

DE,  <  INDBUF+06BH)  iaddr  11  ever. 

04  AB 

200 1 

0137 

JR 

NZ, USEFHLF  5  odd,  use  1st  half 

04  AD 

EB 

0138 

EX 

DE.HL  Seven,  use  2nd  half 

04AE 

7C 

0 1 39 

USEFHLF  LD 

A,  H 

0  4AF 

B5 

0140 

OR 

L 

04  BO 

2&U6 

0141 

JR 

Z, NOINDP  SNG  INDIRECT  PTRS 

0142 

; — GET  FIRST 

ORDER  INDIRECT  POINTER  BLOCK — 

0143 

; — NOTE:  HL  c 

ontair.s  addr  11  =  pointer  block  r.um — 

04  B  2 

CDS 005 

0144 

CALL 

CNVBLK  5  BLK  TO  T  and  S 

04  B5 

c DCS 05 

0145 

CALL 

RD I NDPB  ; Re  ad  ptr  b 1 o c k 

04  B  8 

DD21F501 

0.1  46 

NOINDP  LD 

IX,  INDBUF+ODH  5  SET  BLOCK  INDEX  in  ino 

04BC 

3AC30 1 

0147 

LD 

A, (I NUM)  ; GET  I  number 

04  BF 

E60 1 

0143 

AND 

0  1  7  CK  F  o  r  c»  d  d  o  r  n 

04  Cl 

2005 

0 1  49 

JR 

NZ, ODDINM 

0150 

; — EVEN  I  number ,  Use  2nd  half  inode  BLOCK — 

04C3 

1 1 4000 

0151 

LD 

DE.040H  ; ADD  64 

04  C6 

DDL  9 

0152 

ADD 

I  X  ,  DE 

0 1 53 

7 

- ; 

0154 

;  -fr-K-MA  I N  PROuRAM  LUUF'b^*  ? 

0155 

7 

- ;  (Continued  on  next  page) 
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UNIX  to  CP/M  (Listing  continued,  text  begins  on  page  20) 

Listing  One 


0 1 56 

— READ  10  DIRECT  ADDR  BLOCKS  LOOP — 

04  C  8 

060 A 

0157  ODD I NM  LD 

B , 0 1 0  SLOOP  COUNT 

04  C  A 

C5 

0158  RDNXBK  PUSH 

BC 

0 1 59 

— READ  NEXT 

BLOCK — 

04  CB 

CDF 7 04 

0160 

CALL 

RDBLOCK 

04CE 

Cl 

0161 

POP 

BC 

0162 

— END  RDNXBk 

LOOP — 

04  CF 

1  OF  9 

0 1 63 

D.JNZ 

RDNXBK 

0 1 64 

— END  OF  DIRECTLY  ADDRESSED  BLOCKS — 

0 1 65 

— 

0166 

USE  1ST  INDIRECT  POINTER  BLOCK 

0167 

READ  MAX 

OF  128  BLOCKS  1ST  INDIRECTION 

0168 

— 

04  D1 

DD2 1 6 AO 2 

0 1 69 

LD 

I X , I NDBUFX+2  5  SET  BLOCK  INDEX 

04  El  5 

3EFF 

0170 

LD 

A, OFFH 

04D7 

32E701 

0171 

LD 

( I NDSW > , A  5  SET  INDSW 

04  DA 

(.)  A  y  (_) 

0172 

LD 

B, 0128  SLOOP  COUNT 

0173 

— READ  NEXT 

INDIRECT  BLOCK — 

04DC 

C5 

0174  RDNXIBK  PUSH 

BC 

04  DD 

CDF 704 

0175 

CALL 

RDBLOCK 

04E0 

C 1  • 

0176 

POP 

BC 

04E 1 

1  OF  9 

0177 

DJNZ 

RDNXIBK 

0178 

— QUIT  AT  END  1ST  INDIRECT  BLOCK 

0179 

FILE  SIZE 

E  X  U  E  E  D  S  /  0  k  b  y  t  &  s  — 

0 1 80 

0181 

- DONE,  CLOSE  FILES — 

04  E  3 

1 1 0000# 

0182  DONE  LD 

DE , FCBO 1 

04  E6 

C DO 000# 

0 1 83 

CALL 

CLOSE 

0184 

— SEND  EXIT 

MSG — 

04E9 

1 17801 

0 1 85 

LD 

DE , EXTMSG 

04  EC 

CDOOOO# 

0186  ERXiT  CALL 

PUTMC 

04EF 

C 30 000 

0187 

UP 

OOH  5  BACK  TO  CP/M 

0188 

— FATAL  ERROR — 

04F2 

1 1 B30 1 

0 1 89  ERROR  LD 

DE.MSG2 

04F5 

18F5 

0190 

JR 

ERXIT 

0191 

7 

0192 

**ENE 

MAIN  PROGRAM**  ; 

0193 

SUBROUTINES  BELOW  5 

0194 

7 

0 1 95 

0 1 96 

— READ  ONE  BLOCK— 

0197 

0198  RD BLOCK  : 

0199 

— GET  BLOCK 

NUM  FROM  inode  addr  or  PTR  block — 

04  F  7 

DD6E00 

0200 

LD 

L, < IX+O) 

04FA 

DD660 1 

020 1 

LD 

H ,  ( I  X  + 1  ) 

0202 

— CHECK  FOR 

NULL  addr-  — 

04FD 

7D 

0203 

LD 

A,  L 

04  FE 

B4 

0204 

OR 

H 

04FF 

0205 

JR 

Z , DONE  SEND  FILE 

0206 

— INDEX  TO  NEXT  addr — 

050 1 

DD23 

0207 

INC 

IX 

0503 

DD23 

0208 

INC 

IX 

0505 

DD23 

0209 

INC 

IX 

0507 

3AE70 1 

02  i  0 

LD 

A, ( INDSW) 

050 A 

B7 

021 1 

OR 

A 

05  OB 

2802 

02 1 2 

JR 

Z , NTINDRC 
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050D 

DD23 

02 1 3 

INC 

IX  ; INDIRECT  4  BYTES 

02 1 4 

; — SET  TRK  AND 

SSTN  FROM  BLK  NUM — 

050F 

CD8005 

0215 

NTINDRC  CALL 

CNVBLK 

0216 

; — READ  one  BLK  (4  SECT)  LOOP — 

0512 

0604 

0217 

LD 

B,  04 

0514 

C5 

02 1 8 

RD4SLP  PUSH 

BC 

0219 

; — USE  SCTBUF1 

IN  WRTBUF1  ROUTINE — 

05 1 5 

1 1 0000# 

0220 

LD 

DE  ,  SCTBUF 1  5 SECTuR  BUFI-ER 

0518 

CD8405 

0221 

CALL 

RD 1 SECT  ; READ  1  SECTOR 

0222 

; — SELECT  DISK 

FOR  WRITE 

05  IB 

AF 

0223 

XOR 

A  5  UNIT  A 

05 1 C 

CD0000# 

0224 

CALL 

SELECT 

0225 

; — WRITE  OUT  S 

CTBUF1  USING  FCB01 — 

05  IF 

CD0000# 

0226 

CALL 

WRTBUF 1 

0522 

Cl 

0227 

POP 

BC 

0228 

; — END  RD4SLP 

LOOP  — 

0523 

1  OEF 

0229 

DJNZ 

RD4SLP 

0525 

C9 

0230 

RET 

023 1 

7 

0232 

; - GET  UNIX  FILE  I  NUMBER  FROM  COMMAND  LINE — 

(_)  J  O 

7 

0234 

; — THREE  DIGIT 

S  FOR  I  NUMBER — 

0526 

2 1 6C00 

0235 

GETINIJM  LD 

HL i 06CH 

0529 

CD4B05 

0236 

CALL 

GETDIG  ; GET  DIGIT 

052C 

32C50 1 

0237 

LD 

(DIG1 ) ,A 

052F 

CD4B05 

0238 

CALL 

GETDIG 

0532 

32C60 1 

0239 

LD 

(DIG2) ,  A 

0535 

CD 4 BO 5 

0240 

CALL 

GETDIG 

0538 

32C701 

0241 

LD 

(DIGS) >A 

053B 

1 1C501 

0242 

LD 

DE , D I G 1  ! STRING  PTR  TO  DE 

0243 

; — CONVERT  ASC 

II  DEC  STRING  TO  BIN  NUM — 

053E 

CDOOOO# 

0244 

CALL 

ADCTBIN 

0245 

; — BINARY  I  NUM  IN  HL,  MAX  VALUE = 1 60 — 

054 1 

7D 

0246 

LD 

A ?  L  ; SAVE  LSB  ONLY 

0542 

FEAO 

0247 

CP 

0160 

0544 

D2F204 

R  0248 

UP 

NC, ERROR  ? ILLEGAL  I  NUM 

0547 

32C30 1 

0249 

LD 

( I NUM ) ,  A  ; SAVE  I  NUMBER 

054A 

C9 

0250 

RET 

025 1 

7 

0252 

/-»  “i  nr 

; - GET  DIGIT 

FROM  COMMAND  LINE — 

05 4 B 

7E 

{_)  .~t 

0254 

J 

GETDIG  LD 

A , ( HL ) 

05 4 C 

0255 

INC 

HL 

054D 

FE20 

0256 

CP 

5  SKIP  BLANKS 

0541- 

28FA 

0257 

JR 

Z, GETDIG 

0551 

FE24 

0258 

CP 

■'  *  •"  ;  SK  IP* 

0553 

28F6 

0259 

JR 

Z, GETDIG 

0555 

FEOO 

0260 

CP 

00 

0557 

28  F  2 

0261 

JR 

Z , GETD I G  ; SK I P  ZERO 

0559 

FE3A 

0262 

CP 

03AH  5SKIP  NON  NUM 

055B 

30  EE 

0263 

JR 

NC, GETDIG 

05 5 D 

C9 

0264 

RET 

0265 

7 

0266 

; — CONVERT  I  NUMBER  TO  INODE  TRK  AND  SCTT — 

02 6 7 

7 

05 5 E 

2 AC 30 1 

0268 

CNVINUM  LD 

HL , ( I NUM )  ; GET  I  NUMBER 

0561 

2B 

0269 

DEC 

HL 

0562 

1 10200 

0270 

LD 

DE,  02 
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UMIA  IO  UKflYI  (Listing  continued,  text  begins  on  page  20) 

Listing  One 


0565 

CD 0000# 

027 1 

CALL 

D I V 1 6  5(1  NUM-l>/2 

0568 

1 1 0800 

0272 

LD 

DE, OSH 

0 5 6 0 

19 

0273 

ADD 

HL , DE  ; ( I  NUM  -1)/ 2  +8 

0274 

0275 

; — CONVERT  SEQUENTIAL  SECT  NUM  IN  HL 

0276 

?  TO  TRACK  AND  SECT-TRAN  NUMBER — 

0277 

* 

056 C 

1 1 1 A 00 

0278 

CNVSSNM  LD 

Db.  7  026 

056F 

cboooo# 

0279 

CALL 

D I V 1 6 

0280 

5 — TRACK  =  1  h  t  i  9  e  r  portion  (SSN/26)  — 

0572 

7D 

0281 

LD 

A,  L 

0573 

FE4D 

0282 

CP 

077 

0575 

D2F204 

0283 

UP 

NC, ERROR  ; ILLEGAL  TRACK  NUM 

0578 

32E50 1 

0284 

LD 

( TRACK ) , A  ; SAVE  TRACK 

0285 

i — Relative  set 

-'tor  (sec:  1 1  r  a  n  num)  =  remain  del- (SSN/26)  — 

05  7  B 

7B 

0286 

LD 

A,  E 

0570 

32C90 1 

0287 

LD 

( SCTPTR ) , A  ; SAVE  SECT-TRAN 

057 F 

C9 

U  xi  8  o 

RET 

0289 

0290 

•  — CONVERT  BLOC 

;:K  NUM  IN  HL  TO  TRACK  AND  SECT  — 

0291 

! 

0580 

0292 

CNVBLK  ADD 

HL , HL  ; x  2 

05o  l 

29 

0293 

ADD 

HL ,  HL  ;  :k  4 

0582 

1 8E8 

0294 

JR 

CNVSSNM 

0295 

7 

0296 

? — READ  ONE  UNIX  FILE  SECTOR  INTO  DMA  SF'CIFIED 

0297 

;  IN  DE  AND 

INC  TO  NEXT  SEQUENTIAL  SECTOR — 

0298 

0584 

D5 

0299 

RD1SECT  PUSH 

DE 

0585 

3E01 

0300 

LD 

A ,  0 1 

0587 

CD 0000# 

0301 

CALL 

SELECT  ; SELECT  UNIT  B 

058 A 

Di 

0302 

POP 

DE 

05  SB 

CD0000# 

0303 

CALL 

SETBUFF  ; SET  DMA 

0304 

; — CONVERT  SECT RAN  POINTER  TO  SECTOR — 

058E 

3  AC:  90 1 

0305 

LD 

A, < SCTPTR) 

0591 

21CA01 

0306 

LD 

HL , SECTRAN  ; BASE  TRANS  TAB 

0594 

85 

0307 

ADD 

A, L  ; ADD  OFFSET 

0595 

6F 

0308 

LD 

L,  A 

0596 

300 1 

0309 

JR 

NC , NOCARY 

0598 

33 

03 1 0 

INC 

HL 

031  1 

; — GET  SECTOR 

NUM  FROM  SECTRAN  T ABLE — 

0599 

7E 

0312 

NOCARY  LD 

A, (HL) 

059 A 

32 £60 1 

03 1 3 

LD 

(SECT), A  5  SAVE  SECT 

05 9 D 

FEOO 

0314 

CP 

00  H 

059F 

CAF204 

0315 

JP 

7, ERROR  ! ILLEGAL  SECT  NUM 

05  A  2 

FE1B 

03 1 6 

CP 

27 

05  A  4 

D2F204 

0317 

JP 

NC, ERROR  5  ILLEGAL  SECT  NUM 

0318 

; — LOAD  SECTOR 

NUM  INTO  C — 

05  A  7 

4F 

0319 

LD 

C>  A  ; SECT  FOR  GETSECT 

0320 

5 — LOAD  TRACK  NUM  INTO  B — 

U5A8 

3 A £50 1 

0321 

LD 

A , ( TRACK ) 

U5AB 

47 

0322 

LD 

B,  A  ; TRACK  FOR  GETSECT 

0323 

; — DIRECT  BIOS 

READ  ONE  SECTOR  — 

05  AC 

CD  0(J  00# 

0324 

CALL 

GETSECT  ; READ  SECT  INTO  SCTBUF1 

05  AF 

DAF204 

0325 

JP 

C, ERROR  ! BAD  TRK/SECT  INFO 

0  5  k'  6 

; — INC  SECTOR  NUMBER  FOR  NEXT  READ — 

05B2 

3 AC 901 

0327 

LD  . 

A, (SCTPTR)  *  GET  TAB  OFFSET 

0565 

FE 1  9 

0328 

CP 

025  ; END  ? 

U5B  / 

200 A 

0329 

JR 

NZ , NOTEND 
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0330 

;  — END 

TRACK, 

INC  TRACK  AND  ZERO  SCTPTR — 

05  B  9 

3AE50 1 

0331 

LD 

A , ( TRACK ) 

05BC 

3C 

0332 

INC 

A 

05BD 

32E501 

0333 

LD 

( TRACK ) , A 

05C0 

AF 

0334 

X  OR 

A 

05  Cl 

1 80 1 

0335 

JR 

ENDTK 

05C3 

3C 

0336 

NO TEND 

INC 

A 

05C4 

32C90 1 

0337 

ENDTK 

LD 

( SCTPTR ) , A  ; NXT  SECT 

05C7 

C9 

0338 

RET 

0339 

; 

0340 

5  — READ 

1ST  ORDER  INDIRECT  POINTER  BLOCK— 

0341 

" 

05C8 

1 1 6802 

0342 

RDINDPB 

LD 

DE,  INDBIJFX 

05  CB 

CD8405 

0343 

CALL 

RD1SECT 

OSCE 

1 1E802 

0344 

LD 

DE, INDBUFX+128 

050 1 

COS  405 

0345 

CALL 

RD 1  SECT 

0504 

1  .1 6803 

0346 

LD 

DE,  INDBIJFX +256 

0507 

CD8405 

0347 

CALL 

RD1SECT 

05  DA 

1 1 E803 

0348 

LD 

DE, INDBUFX+384 

0500 

CDS 405 

0349 

CALL 

RD1SECT 

05E0 

C9 

0350 

RET 

0351 

; - END 

OF  PROi 

2»RmM - 

05  El 

( 0000 ) 

0352 

END 

Total 

2nd  Pass 

E  r  r  o  r  s 

0 

•J  F’  S  t  h  k±  t  C  0  U  1  d 

be  .JR s 

== 

1 

7*  o  (..)  /  o 

80  Par  it 

-■  I  j  §  a  i=i  tv 

= 

0 

**  Symbol  Table  ** 


ADCTBIN 

053 F# 

BEG  I N 

0100 

CLOSE 

04  E  7# 

CNVBLK 

0580 

CN v I NUN 

055E 

CNVSSNM 

056C 

CONCRLF 

048B# 

CREATE 

0491# 

DEND 

0 1 C8 

DIG1 

0 1 C5 

D I G2 

0 1 C6 

DIGS 

01C7 

D I V 1  6 

0570# 

DONE 

04  E  3 

ENDTK 

05C4 

ERROR 

04F2 

ERXIT 

04  EC 

EXTMSG 

0178 

FCB01 

04E4# 

ENTFCB 

047C# 

GETD I G 

054B 

GETINUM 

052*6 

GETSECT 

05  AD# 

INDBUF 

0 1 E3 

INDBIJFX 

0268 

INDSW 

01E7 

INUM 

0 1 C3 

MSG  1 

0 1 92 

MSG  2 

0 1  B3 

NOlAR y 

0599 

NOINDP 

04B8 

NOTEND 

05C3 

NTINDBC 

05  OF 

ODD  INM 

04C8 

OPEN 

0000# 

PRNTFN 

0488# 

PUT  TIC 

04  ED# 

F:D  1  SECT 

0584 

RD4SLP 

0514 

RD BLOCK 

04F7 

RD  I  NDF'B 

05C8 

RDNXBK 

04  C  A 

RDNXIBK 

04  DC 

SCTBUE1 

0516# 

SCTPTR 

0 1 09 

SECT 

01E6 

SECTRAN 

0 1 CA 

SELECT 

0588# 

SET BUFF 

058C# 

SIGNON 

0153 

STACK 

0153 

START 

0468 

T  R  m  U  K 

01E5 

USEFHLF 

04AE 

WRTBUF 1 

0520# 

**  Cross  Reference  Table  ** 


Svmbo 1 

ADCTBIN  X 
BEGIN 
CLOSE  X 
CNV8LK 
CNVINUM 


Val  ue 

Defn 

0000# 

0029 

0100 

0036 

0000# 

0028 

0580 

0292 

055E 

0268 

References 
0244 
0 1  S3 

0144  0215 
0 1 26 
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UNIX  to  CP/M  (Listing  continued,  text  begins  on  page  20) 

Listing  One 


CNV3SNM 

056C 

0278 

0294 

CGNCRLF 

X 

oooo# 

0029 

0117 

CREATE 

X 

0000# 

0028 

0 1 22 

DEND 

0 1 C8 

0072' 

D I G 1 

01C5 

0069 

0237 

0242 

DIG. 2 

0 1 C6 

0070 

0239 

DIGS 

01C7 

007 1 

0241 

DIV16 

X 

0000# 

0028 

0271 

0279 

DONE 

04  E  3 

0182 

0205 

ENDTK 

05C4 

0337 

0335 

ERROR 

04  F  2 

0189 

0248 

O  2  © 

0315 

0317 

0325 

ERXIT 

04  EC 

0186 

0 1 90 

EXTHSG 

0178 

005 1 

0185 

FCB01 

X 

0000# 

0028 

0109 

01 15 

0121 

0182 

FNTFCB 

X 

0000# 

0028 

01 1 1 

GETDIG 

054  B 

0254 

0236 

0238 

0240 

0257 

0259 

026 1  0263 

GET I NUM 

0526 

0235 

0124 

GETSECT 

X 

0000# 

0030 

0324 

I NDBUF 

0  1 1 8 

0092 

0128 

0 1 35 

0136 

0146 

INDBUFX 

0268 

0095 

0169 

0342 

0344 

0346 

0348 

I NDSW 

01E7 

0089 

0171 

0210 

I  NON 

0 1 C3 

0066 

0133 

0147 

0249 

0268 

MSG  i 

0192 

0056 

01 13 

MSG  2 

01B3 

006 1 

0189 

NOCARY 

0599 

0312 

0309 

NOINDP 

04  B  8 

0146 

0141 

NO TEND 

05  C  3 

0336 

0329 

NTINDRC 

05  OF 

0215 

0212 

ODD INN 

04C8 

0157 

0149 

OPEN 

X 

0000# 

0029 

PRNTFN 

X 

0000# 

0030 

0116 

F'UTMC 

X 

0000# 

0030 

0104 

0114 

0 1 86 

RD1SECT 

0584 

0299 

0 1 3 1 

022 1 

0343 

0345 

0347 

0349 

RD4SLF' 

0514 

0218 

0229 

RDBLOCK 

04F7 

0 1 98 

0160 

0175 

RDINDPB 

05C8 

0342 

0145 

RDNXBK 

04CA 

0158 

0163 

RDNXIBK 

04  DC 

0174 

0177 

SCTBUF1 

X 

0000# 

003 1 

0220 

SCTPTR 

0 1 C9 

0075 

0287 

0305 

0327 

0337 

SECT 

01 E  6 

0086 

0313 

SEC TRAN 

01CA 

0078 

0306 

SELECT 

X 

0000# 

0030 

0107 

0224 

030 1 

SETBIJFF 

X 

0000# 

0029 

0303 

S I GNON 

0153 

0046 

0103 

STACK 

0153 

0043 

0101 

START 

0468 

0.101 

0036 

TRACK 

01E5 

0084 

0284 

0321 

0331 

0333 

USEFHLF 

04AE 

0139 

0137 

WRTBUFi 

X 

0000# 

003 1 

0226 

I'M I  ictinn  Ona 

End  Listing  One 
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UNIX  to  CPIM  (Listing  continued,  text  begins  on  page  20) 

Listing  Two 


01 AF 

ED  BO 

0052 

LDIR 

0053 

; — CREATE  OUTPUT  FILE — 

0 1 B 1 

1 10000# 

0054 

LD 

DE. FCB02 

01B4 

CD0000# 

0055 

CALL 

CREATE 

0056 

5 - USE  GETCHR 

TO  GET  A  CHARACTER  FROM 

0057 

?  THE  INPUT  A 

SCII  FILE— 

01 B7 

CDOOOO# 

0058 

CHRLOP  CALL 

GETCHR 

0059 

5 — CHECK  FOR  EOF  CHR — 

01  BA 

FE1A 

0060 

CP 

01  AH 

;eof  char 

0 1 BC 

2810 

0061 

JR 

Z , DONE 

;  DONE  IF  EOF 

0062 

? — CHECK  FOR  UNIX  NEW  LINE 

<  LF )  — 

01  BE 

FEOA 

0063 

CP 

OAH 

01  CO 

2007 

0064 

JR 

NZ, NTNWLN 

5  NOT  OAH 

01C2 

3E0D 

0065 

LD 

A>ODH 

; ADD  CR 

01C4 

CDOOOO# 

0066 

CALL 

WRTCHR2 

01C7 

3E0A 

0067 

LD 

A.  OAH 

!  NOW  LF 

0068 

? — USE  WRTCHR2 

TO  PUT  CHARS 

INTO  THE 

0069 

;  OUTPUT  FILE 

: — 

• 

01C9 

CDOOOO# 

0070 

NTNWLN  CALL 

WRTCHR2 

0071 

5 - LOOP  UNTIL 

END  OF  FILE- 

- 

0 1 CC 

1  BE'? 

0072 

JR 

CHRLOP 

0073 

5 - CLOSE  OUTPUT  FILE — 

0  ICE 

1 1 0000# 

0074 

DONE  LD 

DE  ?  FCB02 

01D1 

CDOOOO# 

0075 

CALL 

CLOSE 

01D4 

C 3 0000 

0076 

JP 

OOH 

;  BACK  TO  CP/M 

0077 

; - END  OF ' PROGRAM — 

01D7 

( 0000 ) 

0078 

END 

Total 

2nd  Pass 

E  r  r  o  r  s 

«=  0 

JF's  that  could 

be  JR s 

=  o 

Z80/S 

080  Par  it 

f  l  J  s  a  3  e 

=  0 

Symbol  Table1  ** 


CHRLOP 

01B7 

CLOSE 

01D2# 

CREATE 

01B5# 

DONE 

01CE 

FCB01 

0 1 A 1  # 

FCB02 

01CF# 

FNTFCB 

01 9E# 

GETCHR 

01B8# 

NEW 

0 1 82 

NTNWLN 

01C9 

OPEN 

01A4# 

PUTMC 

0 1 8C# 

S I GNON 

0 1 53 

ST  ACK 

0153 

START 

0185 

WRTCHR2 

01CA# 

Cross  Re  f  e  re  nee  Table 


Svmbo  1 

Va  1  ue 

De  f  n 

References 

CHRLOP 

01B7 

0058 

0072 

CLOSE 

X 

0000# 

0014 

0075 

CREATE 

X 

0000# 

00 1 4 

0055 

DONE 

01CE 

0074 

006 1 

FCB01 

X 

0000# 

00 1 3 

0039  0046 

FCB02 

X 

0000# 

00 1 3 

0042  0051  0054  0074 

FNTFCB 

X 

0000# 

0013 

0041  0044 

GET  CHR 

X 

0000# 

00 1  3 

0058 

NEW. 

0 1 82 

0029 

0050 

NTNWLN 

01C9 

0070 

0064 

OPEN 

X 

0000# 

00 1 4 

0047 

PUTMC 

X 

0000# 

00 1  4 

0035 

SI GNON 

0153 

0022 

0034 

STACK 

0153 

0020 

0032 

START 

0185 

0032 

0017 

WRTCHR2 

X 

0000# 

00 1 3 

0066  0070 

End  Listing  Two 
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A  Small-C  Help  Facility 


One  nice  feature  of  a  “user  friendly” 
operating  system  is  the  presence 
of  a  help  facility.  Many  operating 
systems  have  this  feature,  including  CP/M 
3.0.  Help  programs  are  also  available 
through  the  CP/M  user’s  group.  This 
article  presents  a  different  kind  of  help 
facility,  one  that  is  hierarchical  in  opera¬ 
tion,  detailing  information  about  topics 
that  have  subtopics,  recursively. 

This  program  is  modeled  after  the 
Digital  Equipment  Corporation  VAX  VMS 
3.0  help  program.  As  presented,  it  allows 
nesting  of  subtopics  to  any  predefined 
depth  (default  is  24,  which  can  be 
changed),  and  when  the  carriage  return 
is  pressed  without  a  topic  being  entered, 
the  stack  pops  back  one  level.  If  the 
stack  pops  out  completely,  the  program 
returns  control  to  the  calling  routine.  At 
each  new  stack  level,  the  list  of  available 
topics  is  presented  (except  for  initial  en¬ 
try).  If  an  unmatched  topic  is  entered, 
the  program  apologizes  for  not  having 
information  on  the  subject  and  again  lists 
the  available  topics  at  the  current  stack 
level. 

Because  the  program  is  stack  oriented, 
it  allows  duplication  of  topics  so  long  as 
that  duplication  is  not  on  a  level  equal  to 
the  current  branch  of  the  topic  tree.  For 
example,  the  main  tree  branch  might  have 
topics  such  as  HELP,  SORT,  PRINT, 
and  EDIT,  while  the  next  level  down  for 
the  SORT  branch  might  contain  HELP, 
PATTERN,  and  FILES  as  subtopics.  The 
term  HELP  is  present  in  both  levels,  but 
the  program  does  not  confuse  the  two. 
On  the  other  hand,  a  scheme  containing 
HELP,  PATTERN,  PATTERN,  and  FILES 
on  the  subtopic  branch  for  SORT  is  in¬ 
valid.  Also  note  that  any  branch  in  the 
hierarchy  may  echo  the  term  that  was 
used  to  create  the  branch;  that  is,  HELP 
HELP  HELP  would  be  a  valid  set,  just  as 
SORT  HELP  is  valid  in  the  above  example. 
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The  programs  included  in  this  article 
implement  a  systemwide  help  facility. 
The  data  file  presented  as  an  example 
(Table  I,  page  41)  contains  information 
about  various  utilities,  including  Ed 
Ream’s  screen-oriented  editor,  here  re¬ 
named  ED2. 

General  Description 

The  programming  is  in  Small-C.  It 
compiles  under  the  unmodified  version 
distributed  by  The  Code  Works.  Because 
it  uses  only  the  simple  constructs  made 
available  through  that  subset  of  C,  it 
should  be  highly  portable.  (A  note  to 
those  readers  who  might  object  to  my 
less  than  purist  use  of  the  C  language 
constructs  and  various  function-naming 
schemes:  This  program  works!  For  me, 
the  major  accomplishment  was  to  imple¬ 
ment  a  hierarchical  stack  pop/push  algo¬ 
rithm  in  a  language  where  the  GOTO  sim¬ 
ply  doesn’t  exist.  I  have  found  through 
trial  and  error  that  for  the  most  part 
Small-C  doesn’t  like  recursion.  Therefore, 

I  managed  to  accomplish  the  same  thing 
through  the  judicious  use  of  the  WHILE 
statements,  as  the  coded  routines  can 
attest.) 

The  structure  of  the  programs  is  such 
that  the  essence  of  the  help  facility  can 
be  incorporated  into  any  application 
program.  The  file  HLP.C  (Listing  One, 
page  46)  is  an  include  file  calling  in 
HLPDEF.C  (Listing  Two,  page  46)  and 
HLPPGM.C.  HLPDEF.C  contains  the  ap¬ 
propriate  parameters  for  the  application, 
such  as  stack  size,  stack  depth,  etc. 
HLPPGM.C  (Listing  Three,  page  46)  con¬ 
tains  the  actual  program  code.  All  global 
data  references  and  function  names  in  the 
program  are  preceded  by  the  letters  HLP. 
In  this  way  I  hope  to  avoid  conflicts  with 
other  programs. 

The  compiled  program  requires  ap¬ 
proximately  7K  bytes.  This  may  seem  a 
bit  much,  but  it  includes  a  considerable 
amount  of  stack  handling  code.  In  com¬ 
puting  the  application  program’s  memory 
requirements,  the  size  of  the  data  stacks 
(as  defined  in  HLPDEF.C)  also  must  be 
considered.  In  the  listings  the  stacks  are 
set  up  for  a  systemwide  facility  and  re¬ 
quire  24K  bytes. 

The  program  requires  that  two  de¬ 
fined  variables  be  set  up  by  the  applica¬ 
tion  program.  They  are  NULL  and  CR 
(ASCII  null  and  carriage  return).  Because 
these  should  already  be  in  the  application 
program,  the  help  facility  simply  borrows 
them. 

One  difficulty  in  using  Small-C  is 


that  you  cannot  nest  #includes.  The  pro¬ 
grammer  therefore  is  faced  with  a  minor 
decision  in  compiling  the  application. 
Either  the  HLP.C  file  can  be  eliminated 
and  the  application  can  call  the  two  in¬ 
cludes  (HLPDEF.C  and  HLPPGM.C)  di¬ 
rectly,  or  the  C80  compiler  can  be  used 
to  specify  the  application  program  and 
HLP.C  at  two  subsequent  “Input  File” 
prompts. 

Technical  Description 

The  internal  data  structure  portray¬ 
ing  the  hierarchy  represents  a  multi-link 
descent  tree.  Figure  1  (page  45)  shows  a 
conceptual  view  of  the  tree.  Each  node 
(except  for  the  root  node)  is  a  textual 
description  of  the  current  position  within 
the  structure.  The  links,  one  or  more  per 
node,  are  the  descent  mechanism:  they 
are  the  keywords  that  provide  the  path 
required  to  change  position  within  the 
tree. 

In  Figure  1,  the  root  node  has  sev¬ 
eral  named  descent  paths.  These  links  are 
siblings  to  one  another:  they  each  point 
to  a  textual  node  describing  the  then- 
current  location.  Thus  the  node  at  SORT, 
one  level  down  in  the  hierarchy,  is  a  gen¬ 
eral  description  of  the  sort  program.  Each 
sibling  also  contains  a  pointer  to  the  first 
descent  path  from  the  newly  defined 
node.  This  link,  in  its  turn,  acts  exactly 
like  the  initial  link  from  the  root  node. 

Therefore,  every  link  provides  a  des¬ 
cent  path  to  a  newly  defined  node;  a 
node  terminates  every  descent  path;  and 
there  is  a  potential  recursion  beginning  at 
every  node.  For  example,  in  Figure  1  the 
node  at  the  termination  of  the  descent 
path  made  up  of  the  keywords  SORT, 
PATTERN,  and  FIELD  will  describe  how 
a  field  is  defined  to  the  sort  program. 

The  combination  of  keywords  must 
always  be  unique.  Even  though  a  given 
keyword  may  be  used  in  any  other  posi¬ 
tion  in  the  path,  no  two  sibling  descent 
paths  may  have  an  identical  keyword.  The 
level  of  descent  is  not  important.  Both 
SORT  HELP  and  EDIT  HELP  are  valid, 
since  SORT  and  EDIT  are  separate  nodes, 
which  means  the  two  HELPs  are  not 
siblings. 

Following  the  descent  tree  is  a  hier¬ 
archical  process.  In  principle,  the  tree  can 
be  descended  from  branch  to  branch  at 
any  node  in  the  current  descent  path 
simply  by  switching  to  another  sibling 
at  any  level,  from  0  (root)  to  n  (deepest 
climbed).  Thus  the  path  SORT  PATTERN 
FIELD  (yielding  a  description  of  how  to 
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Table  I 

An  example  of  a  Help  File 


HELP 

The  system  HELP  facility  is  provided  to  make  information  available 
to  the  system  user.  It  may  be  configured  for  the  novice's  use  in 
working  with  CP/M,  or  a  specific  application  system.  For  the  more 
experienced  user,  it  can  be  made  to  provide  a  set  of  reminders  for 
those  functions  which  are  not  'on  the  tip  of  the  tongue'. 

/* 

HELP  USING 

To  use  the  HELP  program,  enter  one  of  the  topics  listed  as  ready  to 
be  displayed.  (You  may  re-list  those  topics  by  entering  '?'  to  the 
prompt.)  As  information  is  provided  about  a  topic,  you  may  note  a 
list  of  further  information  available,  and  a  request  for  a  subtopic.  If 
you  enter  a  'return'  by  itself,  you  will  back-out  of  the  subtopic 
level,  returning  to  the  same  level  as  the  topic  just  displayed.  The 
topic/subtopic  scheme  is  hierarchical,  with  up  to  24  levels  of  sub- 
topic  information  available.  If  you  respond  'return'  to  the  highest- 
level  prompt  ('topic'),  the  program  will  terminate. 

/• 

HELP  NEW 

You  may  create  new,  or  modified,  help  text,  by  modifying  the  file, 
'HELP.HLP'.  The  syntax  of  the  file  is  as  follows: 

line  1  —  The  proper  syntax  of  the  topic/subtopic  name 
lines  2- (n - 1 )  —  The  text  of  the  topic/subtopic 
line  n  —  Must  be  7" 

/* 

HELP  NEW  NAME 

The  proper  syntax  of  the  topic/subtopic  name  is: 

1  to  n  tokens,  may  be  capitalized,  in  a  single  line,  and  separated 
by  at  least  a  single  space  between  each  token. 

Tokens  1  to  (n—  1 )  must  be  duplicates  to  another,  earlier  de¬ 
fined,  topic/subtopic  name.  (If  only  one  token,  it  must  be 
unique.) 

/* 

HELP  NEW  FILE 

All  topic/subtopic  definitions  must  be  in  the  same  file  (HELP.HLP). 
Each  set  of  lines  1-n  (at  least  3  lines  per  set),  must  follow  each 
other  in  the  file,  one  after  the  other. 

/* 


ED2 

The  full  screen  editor.  This  program  can  be  used  to  modify  any 
ASCII  stream  file  (such  as  source  programs).  It  provides  a  preview  of 
the  file  being  edited,  each  line  shown  in  context  with  its  neighbors 
in  the  file. 

This  program  is  a  modified  version  of  that  as  presented  by  Edward 
K.  Ream  in  Dr.  Dobbs  Journal,  Jan-82. 

There  are  three  basic  modes  of  operation:  Command,  Edit,  and 
Insert. 

/* 

ED2 COMMAND 

Command  mode  is  the  most  powerful  editing  mode,  providing  sev¬ 
eral  functions  which  can  affect  the  entire  file  at  once. 

/* 

ED2  COMMAND  APPEND 

This  command  inserts  a  named  file  into  the  buffer  at  the  current 
cursor  position.  Format: 

append  file.ext 

ED2  COMMAND  CHANGE 

This  command  makes  changes  to  lines  within  a  specified  line  range 
(if  not  given,  then  the  whole  file).  The  changes  are  of  a  substitution 
nature,  replacing  each  occurrence  of  a  pattern  string  with  another 
string.  Format: 


change  <range> 
search  mask?  mask 
change  mask?  new 

/* 


ED2  COMMAND  TABS 

This  command  is  used  to  set  the  current  editing  session's  tab-size. 
The  default  is  a  tab  every  8  characters.  Use  of  this  command  can 
change  that  to  any  specified  value.  Note:  use  of  non-standard  tab 
settings  can  produce  unpredictable  results  when  a  file  is  printed 
outside  of  the  editor.  Format: 

tabs  <n> 

/* 

ED2  EDIT 

This  mode  allows  manipulation  within  the  text  buffer,  and  corre¬ 
spondingly  changes  the  CRT  screen.  There  are  several  commands 
available  for  EDIT  mode: 

/* 

ED2  EDIT  SPACE 

This  command  positions  the  cursor  one  position  to  the  right,  except 
if  it  is  already  at  the  extreme  rightmost  position  of  the  current 
line.  Format: 

type  a  space 

/* 

ED2  EDIT  B 

This  command  positions  the  cursor  to  the  beginning  of  the  current 
line.  Format: 

type  a  'b' 

/* 

ED2  EDIT  C 

This  command  places  the  editor  into  command  mode.  Format: 
type  a  'c',  or  alternatively,  type  a  'esc' 


ED2  EDIT  X 

This  command  allows  substitution  of  a  specified  character  for  the 
one  at  the  cursor  position.  It  is  a  one-character  only  substitution. 
Format: 

type  a  'xy'  where  y  is  the  change  mask 

/* 

ED2  INSERT 

This  mode  allows  for  actual  insertion  of  text.  All  special  characters 
are  operable  in  this  mode,  but  the  EDIT  mode  commands  do  not 
function.  Text  is  collected  until  either  the  buffer  is  full,  or  the 
editor  is  returned  to  some  other  mode. 

/* 

ED2  SPECIAL 

There  is  a  collection  of  special  edit  commands  which  operate  both 
in  EDIT  and  INSERT  mode.  These  perform  functions  which  are 
not  mode  dependent,  but  rather  are  useful  in  any  mode.  Some 
of  these  commands  are  also  allowed  in  COMMAND  mode.  Most  of 
them  leave  you  in  EDIT  mode,  however  a  few  will  redirect  you  to 
one  of  the  other  modes: 

/* 

ED2  SPECIAL  UP 

This  command  allows  you  to  reposition  the  cursor  upward  one  line 
(unless  it  is  already  at  the  beginning  of  the  text  buffer).  The  editor 
is  placed  into  EDIT  mode.  Format: 

type  a  'control -r' 

/* 
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(Continued  from  page  41) 

ED2  SPECIAL  DOWN 

This  command  allows  you  to  reposition  the  cursor  downward  one 
line  (unless  it  is  already  at  the  end  of  the  text  buffer).  The  editor  is 
placed  into  EDIT  mode.  Format: 

type  a  'control -d' 

/* 

ED2  SPECIAL  LEFT 

This  command  allows  you  to  reposition  the  cursor  one  character 
closer  to  the  beginning  of  the  current  line  (unless  it  is  already  at  the 
beginning  of  the  line).  The  editor  remains  in  the  current  mode.  This 
command  may  also  be  used  in  the  command  mode.  Format: 

type  a  'left-arrow' 

/* 

ED2  SPECIAL  RIGHT 

This  command  allows  you  to  reposition  the  cursor  one  character 
farther  from  the  beginning  of  the  current  line  (unless  it  is  already  at 
the  extreme  right  of  the  CRT).  The  editor  remains  in  the  current 
mode.  Format: 

type  a  'right-arrow' 

/* 

ED2 SPECIAL  INSERT 

These  commands  allow  you  to  add  lines  in  a  prior  existing  text: 

/* 

ED2  SPECIAL  INSERT  UP 

This  command  moves  the  edit  buffer  down  one  line  and  allows  you 
to  start  entering  text.  The  new  text  is  AHEAD  of  the  prior  text 
where  the  cursor  had  been  before  the  command.  Note  that  the 
insert  is  by  line,  the  editor  will  not  break  apart  the  current  line 
before  making  room  for  the  new  text.  The  editor  is  placed  into 
INSERT  mode.  Format: 

type  a  'up-arrow' 

/* 

ED2  SPECIAL  INSERT  DOWN 

This  command  moves  the  cursor  down  one  line  and  pushes  the  text 
after  the  current  line  down  two  lines,  creating  a  blank  line  where 
you  can  insert  new  text.  The  new  text  is  BEHIND  that  of  the  prior 
text  where  the  cursor  had  been  before  the  command.  Note  that  the 
insert  is  by  line,  the  editor  will  not  break  apart  the  current  line 
before  making  room  for  the  new  text.  The  editor  is  placed  into 
INSERT  mode.  Format: 

type  a  'return' 

Note:  during  the  normal  course  of  entering  text,  pressing  'return' 
is  actually  enacting  the  special  insert  down  command! 

/* 

ED2 SPECIAL  DELETE 

These  commands  allow  deletions  within  the  text  body: 

r 

ED2  SPECIAL  DELETE  LINE 

This  command  deletes  the  line  on  which  the  cursor  currently  rests. 
There  is  no  effect  on  edit  mode.  This  command  may  be  used  in 
COMMAND  mode.  Format: 

type  a  'del' 


/* 

ED2  SPECIAL  DELETE  CHARACTER 

This  command  deletes  the  character  AHEAD  of  the  cursor  (unless 
the  cursor  is  positioned  at  the  beginning  of  a  line).  There  is  no  effect 
on  edit  mode.  This  command  may  be  used  in  COMMAND  mode. 
Format: 

type  a  'back-space' 

Note:  This  command  is  normally  used  while  entering  text  in  the 
INSERT  MODE. 

/* 

ED2  SPECIAL  UNDO 

This  command  is  useful  for  restoring  a  current  line's  original  value 
when  you  have  begun  to  change  it,  but  decided  to  leave  it  as  it  was. 
There  is  no  change  to  the  edit  mode.  This  command  may  be  used  in 
COMMAND  mode.  Format: 

type  a  'control -x' 

/* 

ED2  SPECIAL  INSERT 

This  command  places  the_editor  into  JNSERT  mode.  The  insertion 
begins  AHEAD  of  the  current  cursor  position.  Note:  a  line  will  not 
wrap  to  the  next  if  sufficient  characters  are  entered  to  push  it  to  the 
extreme  right  of  the  CRT.  Therefore,  when  inserting  into  an  existing 
line,  the  rightmost  characters  of  the  line  may  have  to  be  deleted  to 
make  room  for  the  new  text.  (One  assumes  they  will  be  re-entered 
later.  .  .)  This  command  may  be  used  in  COMMAND  mode.  Format: 

type  a  'control -n' 

/* 

ED2  SPECIAL  EDIT 

This  command  places  the  editor  into  EDIT  mode.  The  cursor  is 
positioned  at  the  same  place  as  it  was  last.  This  command  may  be 
used  in  COMMAND  mode.  Format: 

type  a  'control -e' 

/* 

ED2  SPECIAL  COMMAND 

This  command  places  the  editor  into  COMMAND  mode  (even  if  it's 
already  there).  The  current  location  of  the  cursor  is  remembered. 
Format: 

type  a  'esc' 

r 

ED2  SPECIAL  SPLIT 

This  command  splits  a  line  into  two  pieces,  the  leftmost  from  the 
cursor  remaining  where  it  was,  and  the  rightmost  from  the  cursor 
moving  to  the  next  line  downward.  The  editor  is  placed  in  INSERT 
mode.  Format: 

type  a  'control -s' 

/* 

ED2  SPECIAL  JOIN 

This  command  joins  two  tines  fnto  one,  that  is  the  current  line  and 
the  line  immediately  above  it.  Caution:  if  there  isn't  sufficient  room 
to  display  the  new  joined  lines  on  the  CRT  as  a  single  line,  the 
JOIN  is  not  performed!  Format: 

type  a  'control  -p' 

/*  End  Table  I 


define  a  field  to  sort)  can  become  SORT 
HELP  (yielding  a  description  of  how  to 
link  at  the  SORT  node.  In  practice,  the 
program  descending  the  tree  must  first 
“back  off’  from  the  deepest  node  in  the 
path  to  one  where  the  alternate  descent 
path  can  be  followed. 

Operation 

Two  main  function  invocations  are 


required  of  the  application  program,  the 
first  to  hlpinit(“file.dat”)  and  the  second 
to  hlphelpf  ).  Both  are  illustrated  in  the 
HELP.C  listing  (Listing  Four,  page  69). 
The  initial  call  sets  up  the  internal  tables 
by  reading  in  the  named  sequential  file. 
The  help  call  may  be  issued  any  number 
of  times,  depending  on  the  application 
logic.  A  decision  was  made  to  not  display 
the  available  topics  upon  entry  to  the 


help  call,  presuming  that  the  user  could 
be  expected  to  know  on  what  subject 
help  is  required.  Should  the  user  type  in 
a  keyword  not  established  as  a  help  level 
topic  (or  type  a  question  mark,  provided 
no  topic  has  been  named  with  a  question 
mark),  the  program  will  respond  with  a 
list  of  available  subjects. 

Normal  operation  for  the  user,  once 
the  request  for  help  is  made,  is  to  con- 
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Table  II 

A  sample  run  of  the  Help  program 

(User  input  is  in  italics) 


B> 

B>help 

Help  System  Program 
Topic?  help 

The  system  HELP  facility  is  provided  to  make  information  available 
to  the  system  user.  It  may  be  configured  for  the  novice's  use  in 
working  with  CP/M,  or  a  specific  application  system.  For  the  more 
experienced  user,  it  can  be  made  to  provide  a  set  of  reminders  for 
those  functions  which  are  not  'on  the  tip  of  the  tongue’. 

Additional  information  is  available  for 

USING 

NEW 

Sub-Topic?  using 

To  use  the  HELP  program,  enter  one  of  the  topics  listed  as  ready 
to  be  displayed.  (You  may  re-list  those  topics  by  entering  '?'  to  the 
prompt.)  As  information  is  provided  about  a  topic,  you  may  note  a 
list  of  further  information  available,  and  a  request  for  a  subtopic.  If 
you  enter  a  'return'  by  itself,  you  will  back-out  of  the  subtopic 
level,  returning  to  the  same  level  as  the  topic  just  displayed.  The 
topic/subtopic  scheme  is  hierarchical,  with  up  to  24  levels  of  sub- 
topic  information  available.  If  you  respond  'return'  to  the  highest- 
level  prompt  ('topic'),  the  program  will  terminate. 

Sub-Topic?  new 

You  may  create  new,  or  modified,  help  text,  by  modifying  the  file, 
'HELP.HLP'.  The  syntax  of  the  file  is  as  follows: 

Line  1  —  The  proper  syntax  of  the  topic/subtopic  name 
lines  2-(n-1)  —  The  text  of  the  topic/subtopic 
line  n  —  Must  be  '/*’ 

Additional  information  is  available  for 

NAME 

FILE 

Sub-Topic?  name 

The  proper  syntax  of  the  topic/subtopic  name  is: 

1  to  n  tokens,  may  be  capitalized,  in  a  single  line,  and  separated 
by  at  least  a  single  space  between  each  token. 

Tokens  1  to  (n  —  1 )  must  be  duplicates  to  another,  earlier  de¬ 
fined,  topic/subtopic  name.  (If  only  one  token,  it  must  be 
unique.) 

Sub-Topic?  file 

All  topic/subtopic  definitions  must  be  in  the  same  file  (HELP.HLP). 
Each  set  of  lines  1-n  (at  least  3  lines  per  set),  must  follow  each 
other  in  the  file,  one  after  the  other. 

Sub-Topic?  other 

Sorry,  no  information  is  available  for  OTHER 
Additional  information  is  available  for 

NAME 

FILE 

Sub-Topic?  <cr> 

Additional  information  is  available  for 

USING 

NEW 

Sub-Topic?  <cr> 

Additional  information  is  available  for 


HELP 

SORT 

PIP 

PRINT 

ED2 

Topic?  ed2 

The  full  screen  editor.  This  program  can  be  used  to  modify  any 
ASCII  stream  file  (such  as  source  programs).  It  provides  a  preview 
of  the  file  being  edited,  each  line  shown  in  context  with  its  neigh¬ 
bors  in  the  file. 

This  program  is  a  modified  version  of  that  as  presented  by  Edward 
K.  Ream  in  Dr.  Dobbs  Journal,  Jan-82. 

There  are  three  basic  modes  of  operation:  Command,  Edit,  and 
Insert. 

Additional  information  is  available  for 

COMMAND 

EDIT 

INSERT 

SPECIAL 

Sub-Topic?  command 

Command  mode  is  the  most  powerful  editing  mode,  providing  sev¬ 
eral  functions  which  can  affect  the  entire  file  at  once. 

Additional  information  is  available  for 

APPEND 

CHANGE 

CLEAR 

DELETE 

EXIT 

FIND 

G 

LIST 

LOAD 

NAME 

QUIT 

SAVE 

SEARCH 

TABS 

Sub -Topic?  <cr> 

Additional  information  is  available  for 

COMMAND 
EDIT 
INSERT 
SPECIAL 
Sub-Topic?  <cr> 

Additional  information  is  available  for 

HELP 

SORT 

PIP 

PRINT 

ED2 

Topic?  <cr> 

B> 


End  Table  II 


tinue  to  enter  topics  (or  subtopics)  until 
the  requested  information  has  been  deliv¬ 
ered.  When  the  user  is  finished,  the  pro¬ 
gram  can  be  aborted  (if  stand-alone)  by  a 
control-C.  If  the  help  facility  is  incor¬ 
porated  into  an  application  program,  then 
pressing  the  carriage  return  without  enter¬ 
ing  a  topic  will  cause  the  descent  tree 
logic  to  climb  back  one  level.  Should  this 
retreat  return  the  program  to  the  root 


node,  the  application  program  once  again 
will  take  control.  (The  sample  help  pro¬ 
gram  run  included  in  Table  II,  page  43, 
returns  to  CP/M  at  this  point.) 

The  application  programmer  who  in¬ 
cludes  the  help  facility  must  determine 
the  size  of  its  internal  arrays,  based  upon 
the  previously  discussed  considerations. 
Then  an  external  help  file  must  be  pre¬ 
pared.  The  name  of  that  file  is  transferred 


to  the  facility  via  the  hlpinit  call  as  the 
function’s  argument.  The  external  file 
must  not  exceed  the  internal  array  storage. 

How  to  Build  a  Help  File 

Help  files  are  built  using  a  text  editor. 
These  are  ASCII  text  files  with  the  normal 
CP/M  line  and  file  termination  character¬ 
istics.  They  can  be  created  using  the  stan- 
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43 


dard  ED  editor.  I  have  used  Ed  Ream’s 
screen  editor  to  create  them  without  ex¬ 
periencing  any  difficulties. 

Text  to  be  considered  by  the  pro¬ 
gram  as  a  help  file  should  conform  to  the 
following: 

(1)  The  text  that  comprises  the  node  is 
called  a  packet. 

(2)  Each  packet  consists  of  three  parts: 
the  header,  the  body,  and  the  trailer. 

(3)  The  whole  help  file  is  an  assemblage 
of  properly  formatted  packets. 

A  header  is  a  single  line  of  text  (nor¬ 
mally  all  upper  case)  composed  of  a  string 
of  words  that  uniquely  identifies  the 
packet.  If  there  are  n  words  in  the  line, 
then  the  first  (n- 1)  words  must  have  been 
previously  defined,  and  the  nth  word 
must  be  unique  in  its  position.  (A  word 
is  defined  by  being  the  nth  word  in  a 
header  packet.)  Definitions  of  the  first 
(n-1)  words  must  occur  in  a  logical  se¬ 
quence  prior  to  the  definition  of  the  nth 
word.  For  example,  if  a  packet  is  to  be 
defined  for  SORT  PATTERN  FIELD, 
then  packets  must  already  exist,  in  se¬ 
quence,  for  SORT  and  for  SORT  PAT¬ 
TERN.  In  this  example,  SORT  PATTERN 
must  follow  SORT.  Other  definitions  may 
be  interleaved,  such  as  for  SORT  ORDER, 
so  long  as  SORT  precedes  both  SORT 
PATTERN  and  SORT  ORDER,  and  SORT 
PATTERN  precedes  SORT  PATTERN 


FIELD. 

The  body  of  the  packet  is  composed 
of  as  many  lines  of  text  as  are  required 
to  convey  the  node’s  meaning.  This  is 
displayed  followed  by  a  line  for  each 
subtopic  keyword  (descent  tree  link  from 
the  current  node).  Following  the  display 
of  the  subtopic  keywords  is  a  query  ask¬ 
ing  for  the  user’s  further  request.  The  size 
of  the  body  may  be  limited  by  the  in¬ 
tended  display  device.  If  a  hard-copy 
terminal  is  used,  there  may  be  no  limit 
to  its  size.  When  a  CRT  is  used,  however, 
the  whole  display  (from  original  topic/ 
subtopic  request,  through  body  and  sub- 
topics,  to  the  new  query)  will  probably 
need  to  fit  in  24  lines. 

The  trailer  is  a  single  two -character 
string  containing  It  is  used  as  a 

separator  between  packets.  Only  this  sep¬ 
arator  line  can  contain  “/*”  in  its  first 
two  positions. 

Summary 

Since  an  operating  system  based  in 
Small-C  was  presented  in  DDJ  No.  77 
March  1983,  this  help  utility  may  be  of 
significant  interest  to  the  DDJ  commu¬ 
nity.  In  concert  with  the  screen-oriented 
editor  and  current  versions  of  Small-C,  a 
fairly  complete  operating  system  environ¬ 
ment  can  be  constructed.  Having  used 
Small-C  to  build  sort  and  print  programs, 
I  am  extremely  grateful  to  DDJ  for  the 


opportunity  both  to  experiment  with 
Small-C  and  to  contribute  to  the  growing 
body  of  published  programs  in  Small-C. 
The  multi-branch  tree  structure  of  the 
internal  data  representation  for  building 
and  displaying  help  file  texts  theoretically 
could  end  up  controlling  a  multi-level 
directory  hierarchy  in  a  Small-C  based 
operating  system  or  serving  as  the  founda¬ 
tion  of  a  hierarchical,  Small-C  based, 
Data  Base  Management  system.  The  initial 
loading  of  the  data  file  from  the  diskette, 
which  is  strictly  a  function  of  the  speed 
of  data  transfer  from  storage  media,  may 
take  a  significant  amount  of  time  (de¬ 
pending  on  the  file  size).  Once  loaded, 
however,  the  threading  and  display  algo¬ 
rithms  are  quite  fast. 


(Listings  begin  on  page  46) 
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Help  Facility  (Text  begins  on  page  40) 

Listing  One 


/* 

*  Include  file  -for  HELP  facility,  if  included  in  any  program 

*  then  also  brings  in  the  subordinate  files 
*/ 


^include  hlpdef.c  /*  the  particular  custom  tailored  help  sizes  */ 

#include  hlppgm.c  /*  the  programatic  code  of  the  facility  %/ 


/%  end  of  the  help  include  file  %/ 


End  Listing  One 


Help  Facility 

Listing  Two 


/* 

*  The?  custom  tailored  section  of  the  HELP  facility. 

*  This  include  file  should  be  evaluated  for  each  new  usage,  and 
%  modified  to  an  appropriate  size. 

*  The  buffers  are  sized  for  a  standalone  help  program  as 

*  presented  here. 

*/ 


#def i ne 
#def i ne 
#def i ne 
ttdef i ne 
#def i ne 
#def  i  ne? 


HLPSZBUF 

HLPSZTF’C 

HLF'SZNME 

HLF'SZTXT 

HLF'NESTD 

HLPSZTKN 


80  /%  size  of  each  text  buffer  */ 

200  /%  #  of  topics  available  in  memory  # / 

1000  /%  #  of  bytes  of  topic  name  text  t/ 

24000  /%  #  of  bytes  of  topic  text  %/ 

24  /%  nesting  level  maximum  %/ 

160  /*  token  buffer  size,  2*HLPSZBUF  */ 


i  nt 

hi  pi nf 1  ; 

i.  nt 

hi ptphsb ; 

/* 

int 

hi ptptsb ; 

/# 

i  n  t: 

hlpnotpc; 

/% 

int 

hi pnotkn ; 

/% 

int 

hi proot ; 

/* 

/%  input  file  number  %/ 
subscript  to  topic  name  text  area  %/ 
subscript  to  topic  text  area  %/ 
number  of  topics  in  memory  % / 
number  of  tokens  in  line  %/ 
root  of  all  chains  %/ 


int  hi  ptopi c  CHLPSZTPCD ; 
i  nt  hi  psbrixt  CHLPSZTPC3 ; 
int  hlpsbtpcC HLPSZTPC 1 ; 
int  hi ppttxt CHLPSZTPCD ; 
int  hi  ppttkn  C  HLF'NESTD  1  ; 


/%  pointers  to  topic  name  text  #/ 

/#  linked  list  of  current-level  siblings  #/ 
/%  linked  list  of  sub-topics  % / 

/%  pointers  to  topic  text  %/ 

/%  pointers  to  each  token  %/ 


char  hi pnameCHLPBZNMEl ; 
c h ar  h  1  p t ex  1 1  HLF’SZTXT  1 ; 
c h ar  h  1  p t  okn  C HL.F'S Z TKN  3  ; 


/# 

topi  c 

name 

text  %/ 

/% 

topi  c 

text 

%/ 

/% 

token 

buffer  %/ 

/%  end  of  hlpdef.c  include  file  %/ 


End  Listing  Two 


Help  Facility 

Listing  Three 

%  This  routine  is  the  programatic  code  of  the  HELP  facility. 

#  It  is  designed  to  display  a  hierarchical  presentation  of  text 
%  from  the  file  in  hlpflnme,  by  topic/sub-topic.  It.  is  called 
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3ft  at  least  twice  in  the  calling  program..  The  first  call  to 

*  hlpinitO  reads  in  the  data  from  the  file,  and  establishes  the 

*  necessary  internal  pointers.  The  second  call  to  hlphelpO  is 

*  interactive  with  the  user,  responding  to  requests  for  topic:/ 

*  sub— topic. 

#/ 


h  1  pi  n i  t  ( h  1  pf  1  rime ) 
char  fchlpflnme; 


i  n  t.  c  ; 

/% 

%  This  is  the  appropriate  call  to  cause  the  help  facility  to  load 
*  in  the  data  file  (hlpflnme)  and  build  the  internal  pointer  base. 
*/ 

c::=h  1  popen  (hi  pf  1  nine)  ; 
if  <c!=0)  f 

hlpbuildO  ; 
f cl ose (hi  pi nf 1 ) ; 


hi phel p  (  ) 
i 


/* 

*  This  is  the  appropriate  cal  1  to  query  the  user  for  topic/sub-topic 

#  displays..  It  returns  when  no  further  topics  are  entered. 

*/ 


hi pdi spl  ( )  ; 


h  1  p op  en  ( h  1  p  f  1  n  me ) 
char  fchlpflnme; 


/* 

%  Open  the  help  file  containing  the  text,  which  will  be  decoded 
#  and  stored. 

%/ 

i  n  t  c: ; 


hi  pi  nf  1  =f  open  (hi  pf  1  nine?,  "r  "  )  ; 
i  f  (hi  pi nf 1 ==NULL>  { 

puts (hi pf 1 nme) ; 

puts ( "  file  not  found"); 

putchar <CR) ; 

return (0) ; 


(Continued  on  page  50) 
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Help  Facility  (Listing  continued,  text  begins  on  page  40) 

Listing  Three 


return  ( 1 )  ; 


hi pbui 1 d  ( ) 

£ 

/* 

*  Build  topic  table 
%/ 

int  switch;  /%  0=header,  l=te>:t  %/ 

int  1; 
int  c ; 

int  p;  t%  link— in  switch  l=ok,  else  not 

char  1 ineCHLPSZBUF3 ;  /*  internal  butter  */ 

hi ptphsb=l ; 
hi ptptsb=0; 
hi pnotpc=l ; 
swi.  tch—O; 
hi proot=0; 

wh i 1 e  ( < 1 =h 1 pg 1 1 n ( 1 i ne ) ) >0  >  £ 

it  (switch==0)  £ 

hi puprcs ( 1 i ne) ;  /*  be  sure  all  uppercase  %/ 

/%  tirst  line  ot  set  is  topic  header  %/ 
hi pbl tk ( 1 i ne) ;  /%  extract  all  tokens  %/ 

swi tch=l ;  /  #  tlip  switch  %/ 

p=hlplink<);  /*  link  in  this  item  %/ 
it  (p==l)  £  /%  record  only  it  valid  % / 

hlptopicChl pnotpc  3=hl ptphsb ; 
hi psvtpc ( 1 i ne) ; 
hi psbnxt Chi pnotpc  3=0; 
hi psbtpc  Chi pnotpc  3=0; 
hi  ppttxt:  Chi  pnotpc  3=h  1  ptptsb  ; 
hi pnotpc++; 


el  se  £ 

hlpsvtxt  <1 ine) ; 

it  ( <lineC03==’/’ )  &  ( 1 i neC 1 3==' *  7 ) )  £ 

switch=C);  f%  re-t  lip  %/ 


h  1  p  1  i  n  k  ( ) 


/* 

*  Thread  in  this  new  topic/subtopic  into  the  heirarchy 

%/ 

i  rit  tst ,  c  ,  r  ,  thread  ,  k  ; 
int  e , t ; 

char  tkn CHLPSZBUF3 , tpcCHLPSZBUFl ; 
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i  n  t:  t. ,  s ,  v ; 


if  (hi proot==0)  i 

/ %  first  time  in  %/ 
hi proot=hl ptphsb ; 
e=h 1 pptt kn  COD ; 
return ( 1 ) ; 

1 

J 

/%  not  first,  find  match  if  possible  %/ 
thread=hl proot ; 

k:=0; 

while  (k<=hlpnotkn)  f 
r=0; 
tst=l ; 

while  (tst==l )  { 

/%  get  token  name  %/ 
v=0 ; 

t=hl pptt  kn Ck 3 ; 

while  ( (s=hlptokntt++3) !=NULL>  C 
tkn  C  v++3=s; 

1. 

J 

tknCv3=NULL;  /%  terminate  it  %/ 
/%  get  topic  at  thread  %/ 
t=hlptopicC  thread  3 ; 
hlpgttpc  (tpc , t ) ; 

/%  compare  token  to  topic  %/ 
c=hlpcmpr (tkn, tpc) ; 
return (2) ; 


*  if  here,  cannot  be  on  the  last  token 
%  and  must  be  duplicate 
%  until  at  bottom  of  hierarchy 

*/ 

if  (r ! =2)  i 

return (2) ; 

\ 

J 

/*  still  a  duplicate  from  here  on  %/ 
el  se  { 

/% 

%  if  no  sub-topics  and  is  next  to  last  token, 
#  then  link  in  as  a  new  sub— topic 

*/ 

if  (hi psbtpc l thread 3~=0)  t 

/%  nothing  in  heirarchy  %/ 
if  ( k== (hi pnotkn-1 ) )  € 

hi  psbtpc  Cthread  3=h.l  pnotpc  ; 

/%  add  a  lower  entry  */ 
return ( 1 ) ; 


return (2) ; 


/%  quit  too  soon  %/ 


(Continued  on  next  page) 
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Help  Facility  (Listing  continued,  text  begins  on  page  40) 

Listing  Three 

if  (c==0>  f 
r  =  2; 
break ; 

\ 

J 

if  (hi  psbnxt  C  thread  3==0>  { 

tst=0; 
r  =  l ; 

■>. 

J 

el  se  { 

thread=hl psbnx  1 1  thread  .1 ; 


/%  if  last  token  and  not  matched,  link  in  %/ 
if  < (k==hlpnotkn>  &  (r==l))  { 

hi psbnx t  C thread  3=hl pnotpc ; 
if  (k==0)  i 

e=hl ppttkn  Ck 3 ; 

/%  display  sub -topics  %/ 

■V. 

J 

return  ( 1 ) ; 

\ 

J 

/%  if  last  token  and  still  duplicate,  report  duplicate  %/ 
if  (  (k==hlpnotkrt)  &  (r==2) )  { 

/%  start  down  the  hierarchy  %/ 
thread=hl psbtpc  C  thread  3 ; 


/%  now  look  at  next  token  % / 
k++; 


/%  if  got  here,  MUST  be  a  logic  error  #/ 
puts ("Logic  error????"); 
putchar (CR) ; 
return (2 ) ; 


hlpbl tk (a) 
char  *a; 

/% 

*  Builds  separate  tokens,  separated  by  spaces  in  source  text 

*/ 


i  nt  c: ,  d ,  e,  f  ,  1  ; 

f  =0; 

hi pnotkn-O; 

d=0; 

e=0 ; 

1=0; 


/ %  0=first  char  in  token,  else=l  %/ 
/ %  number  of  tokens  %/ 

/%  subscript  to  aC?3  */ 

/%  subscript  to  hlptoknC?3  %/ 

/%  last  character  looked  at  %/ 


while  ( (c=aCd++3 ) ! =0)  { 

if  ((c==?  ’  )  &  (1==’  ’>>  l 

1  =c ; 
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el  se 


.if  <f ==0)  C 

f  =  l; 

hi  ppttkn  Chi  priot  kn++3=e; 

J 

if  <c=='  ’)  { 

hlptoknCe++3=NULL; 
f  =0; 

J 

el  se  C 

hlptoknCe+-+3=c; 

\ 

J 

1  =c ; 


h  1  p t o kn  C  e++  .1  --MULL ; 
hi pnotkn — ; 


hi pdi spl  ( ) 

C 

/* 

$  Display  stored  text  for  a  match  on  topic  keyword, 

*  logic:  handles  the  hierarchical  nature  of  these  files. 

*/ 

int  ksub; 
i  nt  k  ,  c  ,  t.  st. ,  j  ,  1  ; 

char  keywdCHLPSZBUF] ;  /%  input,  key  word  or  phrase  %/ 

char  1  ineCHLPSZBUFl;  /*  text  buffer  */' 

int  retstck CHLPNESTDD ;  /%  return  thread  stack  %/ 

int  stkl vl , thread; 
i  n  t  t.  x  s ; 

r  etstck  C 0 1 =h 1 proot ; 
stkl vl=0; 

t  s  t  =  1  ; 

while  (tst==l)  C 

if  (stkl vl ! =0)  puts ( "Sub-" ) ; 
hi pgtprm ( "Topi c?  ",keywd>; 
h 1 puprcs ( key wd ) ; 

if  ( keywd C03==NULL )  C  /#  if  null,  pop  out.  */ 
if  (stkl vl ==0)  C 

break;  /*  done  with  this  procedure  %/ 

"V. 

J 

stkl vl — ; 

thr  ead=retstck  C  stk.l  vl  3; 
hlpsubtp  (thread) ; 

\ 

J 

el  se  t 

thread=retstck Cstkl vl ++3 ; 
txs=l ; 

while  ( tx  s== 1 )  C 

k  sub=h  1  p  t  op  i  c  C  t  h r  ead  3  ; 
h .1  p g t: t p c:  (1  i  n e ,  ksub)  ; 
c=hl  pcrnpr  ( keywd  ,  1  i  tie)  ; 

if  (c==0>  C  /#  display  when  equal  %/ 

(Continued  on  page  56) 
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Help  Facility  (Listing  continued,  text  begins  on  page  40) 

Listing  Three 


j“hl pptt>:t [thread  3 ; 
hi pdmptx ( j ) ; 

i  f  (hi psbtpc [ thread  3 ! =0 >  £ 

thread=hl psbtpc [thread  3 ; 
retstck [st kl vl ++3=thread ; 
hi psubtp ( thread ) ; 

\ 

J 

stkl vl — ; 
break ; 

•>. 

J 

thread=h  1  psbn>:  t  [  thread  3  ; 
i f  (thread==0)  £ 

puts  ("Sorry,  no  in-formation  is  ") 
puts ( "avai 1 abl e  for  " ) ; 
puts ( keywd ) ; 
putchar  < CR) ; 

thread=retstck [ — st  kl vl 3 ; 
hlpsubtp (thread) ; 
break ; 


hi psubtp (a) 
int  a; 


%  Print  available  subtopics  at  this  level 
*/ 


int  thread , ksub ; 
char  1 ine[HLPSZBUF3; 


putchar (CR) ; 

puts ( "Addi ti onal  information  is  available  for 
putchar (CR) ; 
putchar (CR) ; 
thread=a ; 

while  <t.hread!=0)  { 

ksub=hl ptopi c [ thread  3  ; 
hlpgttpc (line, ksub ) ; 
puts ( 1 i ne) ; 
putchar (CR) ; 

thread=hl psbnxt [ thread  3 ; 


hi psvtpc (a) 
char  sKa; 


*  Save  last  token  in  name  of  topic 

*/ 
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int  tst,c,d; 

i  n  t  v ,  t ,  s ; 

char  tknCHLF'SZBUFl 


v=0; 

t=hl ppttknChl pnotkn J ;  /%  last  token  in  name  %/ 

while  (  (s=hl  ptokn  Ct++D  )  !  =NULL>  C 
tknC v++D~s; 

J 

tknCv3=NULL;  /%  terminate  it  %/ 

tst= 1 ; 

c=0; 

while  <  t.st==  1 )  i 

d=hl ptoupr ( tk.n  Cc++3 ) ; 
hi pnameChl ptphsb++3=d ; 
if  (d==0)  t 

tst=0; 


hi psvt ;; t  (a ) 
char  #a; 


/# 

%  Save  the  text  -for  a  given  topic 

#/ 

i nt  tst,c,d; 

t.st  =  1 ; 
c=0; 

while  (tst==l)  { 
d=aCc++3 ; 

hi ptext  Chi ptptsb++ l^d ; 
if  <d=*=0)  tst=0; 


hlpgttpc (a, b) 
char  #a; 
int.  b ; 


/* 

%  Get  topic  name  at  location  b 

*/ 

i nt  tst , c , d , e; 

tst=l ; 
e=0 ; 
c=b ; 

(Continued  on  page  62 ) 
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Help  Facility 

Listing  Three 

(Listing  continued,  text  begins  on  page  40) 


while  (tst~:=l>  £ 

d=hl pnametc++l ; 

are++3=d; 

if  (d==0)  tst=0; 


hlpdmptx (a) 
int  a; 

£ 

/% 

*  Display  the  text,  for  topic  by  location  a 

%/ 

int  t  st , c , b ; 

b=l ; 
tst=l ; 

while  <tst==l)  £ 

c=hl ptext  Ca++3 ; 
if  <b==l )  £ 

/%  set  on  if  prior  char  was  null,  or  S>  start  %/ 
if  <c==’ /’ )  £ 

c=hl ptext  £a++3 ; 
if  £ 

tst^O; 

break ; 

} 

el  se  £ 

puts  ( *'/*')  ; 

\ 

J 

> 

y 

b-0; 

if  (c==NULL>  £ 
b=l ; 

putchar <CR) ; 

\ 

J 

el  se  £ 

putchar  <c ) ; 


hi  pgt.  1  n  (1 1  i  ne) 
char  *1  line; 

£ 

/# 

#  Gets  input  line,  will  return  NULL  if  end  of 
file,  or 
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*  CR  is  at  £?nd  of  line 

*/ 


i  =0; 

while  ( (c=getc (hi pi nf 1 > ) >NULL)  i 
1 1 i net i J=c ; 
if  <c==CR>  l 

break ; 

■v 

J 

el  se  £ 

if  (  i < (HLPSZBUF- 1 ) )  f 
i++; 


1 1 ineCi 3=NULL; 
return (c  >  ; 


hi pgtprm  (in,  r  ) 
char  *in,  #r ; 


/% 

#  Get  input  parameter  from  console 

*/ 

puts (m> ; 
gets  <r )  ; 


hi pcmpr (a, b ) 
char  *a,  *b; 

C 

/* 

#  Perform  a  FORTRAN-1 i ke  compare.  Test  a  to  b,  and 

#  return  -1  if  a  less  than  b, 

#  0  if  a  equals  b,  or 

#  1  if  a  greater  than  b. 

*/ 


int  r,s,t,q,c,d; 

r  =0; 
q  =  l  ; 
s=0; 
t=0; 

while  (q==l)  t 

c=aCs++3 ; 
d=bCt++3  ; 

(Continued  on  next  page) 


Dr.  Dobb’s  Journal,  Number  84,  October  1983 


65 

597 


Help  Facility 

Listing  Three 


( Listing  continued,  text  begins  on  page  40) 


if  ( c  <  d  )  { 

/%  first,  is  low  %/ 

r=—  1; 

q=0; 

J 

if  < c >d )  t 

first,  is  high  %/ 

r-lj 

q=0; 


if  (c==0)  {  /%  stop  if  first  over  %/ 

q=0; 

> 

if  (d-=0)  f  /%  stop  if  second  over  %/ 

q=0; 

J 

/%  Note,  if  c  and  d  were  equal,  and  are  now  zero, 

*  then  logically  the  whole  of  each  string  has  been 

#  found . 

#/ 


return  (r ) ; 


hi ptouor (c ) 
i  nt  c ; 

{ 


/* 

%  convert  a  character  to  uppercase 

*/ 


if  ( <c< ’ a ’  )  !  <c>'z’>>  f 

return (c )  ; 

J 

el  se  { 

return (c-32)  ; 


hlpuprcs (a) 
char  #a; 


/* 

*  convert  a  string  to  upper  case 

#/ 

int  c, d; 


c=C>; 

while  (  ( d  =a  t  c  3  >  ! =NULL )  l 

aCc++3=h 1 ptoupr  <  d  >  ; 
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/%  end  of  hlppgm.c  include  module  %/ 

/% 

%  System  HELP  routine. 

# 

#  This  program  is  intended  to  be  used  by  the  novice 

#  user  to  obtain  information  about  the  system  by 
%  typing  HELP  to  the  CP/M  prompt. 

% 

#  It.  queries  the  user  for  a  topic  (and  subsequent 
sub topi cs) 

#  of  interest.  It  is  heirarchical  in  its 
approach  to 

#  response. 

# 

%  The  program  is  coded  as  a  skeletal  example  of  what 
is  required 

#  of  an  application  program  to  incorporate  the  help 
f aci 1 i ty . 

*/ 

ttdefine  NULL  0  /%  ascii  for  nothing  %/ 

ttdefirie  CR  13  /*  carriage  return  %/ 

mai n  ( ) 


hi  pi  nit  (  "HELP.  HL.P"  )  ; 

putsC'Help  System  Program"); 
putchar (CR) ; 
putchar (CR) ; 

hi phel p  < ) ; 


/% 

%  Now  programmer  should  include  the  hlp.c  program  in 
the  cSO  compiler 

*  dialog.  Note  the  hlp.c  contains  includes, 
and  c80  does  not  allow 

*  nesting  of  includes. 

*/ 

/%  end  of  help)  utility  %/ 

End  Listing  Four 
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Attaching  a  Winchester 
Hard  Disk  To  the  S-100  Bus 


It  recently  has  become  possible  to  pur¬ 
chase  a  multi-megabyte  Winchester 
drive  for  a  less-than-astronomical 
price.  For  instance,  Priority  One  Electron¬ 
ics  is  selling  a  Micropolis  8 -inch  drive 
with  a  formatted  capacity  of  35  MBytes 
for  slightly  more  than  $4,000.  This  is 
complete  with  power  supply,  cabinet, 
and,  most  important,  an  intelligent  con¬ 
troller. 

The  drive  consists  of  three  two-sided 
platters  or  six  sides,  one  of  which  is  re¬ 
served  for  supplying  servo  information 
for  the  voice  coil  head  positioner.  Each  of 
the  five  data  surfaces  is  divided  into  580 
tracks  of  12K  capacity.  These  tracks  are 
further  subdivided  into  sectors.  When 
ordering  the  drive,  you  must  specify  the 
desired  number  of  sectors;  24  sectors  of 
5  1 2  bytes  or  12  of  1024  seem  reasonable. 

Because  of  the  controller,  interfacing 
the  drive  to  the  S-100  bus  is  very  simple. 
A  circuit  for  that  purpose,  suitable  for 
wire- wrapping,  will  be  described  in  this 
article.  The  controller  also  simplifies  the 
necessary  software  for  reading  from  and 
writing  to  the  drive. 

The  Controller 

Before  discussing  the  interface,  we 
need  to  know  something  about  the 
controller.  Even  though  I  shall  present  a 
reasonably  detailed  description,  it  is 
essential  that  a  potential  user  get  a  copy  of 
Micropolis’s  documentation.  (I  purchased 
the  Micro- Disk  Maintenance  Manual  from 
them.) 

The  controller,  which  is  Z80  based, 
handles  all  transactions  between  the  com¬ 
puter  and  the  drive.  Connections  between 
it  and  the  host  computer  are  made  at  a 
34-pin  edge  connector  on  which  all  odd- 
numbered  pins  are  grounded.  The  remain¬ 
ing  17  pins  are  arranged  in  sets  as  follows: 
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eight  bidirectional  I/O  data  lines;  two 
strobe  lines  for  read  and  write  (strobes 
are  generated  by  the  host);  and  one  selec¬ 
tor  line  (also  from  the  host)  that  deter¬ 
mines  the  nature  of  the  information  on 
the  bidirectional  bus,  i.e.,  whether  it  is 
COMMAND/STATUS  or  READ/WRITE 
data.  The  remaining  six  lines  are  not  of 
immediate  importance  for  our  purposes. 

Because  the  data  bus  is  bidirectional, 
you  must  pay  careful  attention  to  the 
timing  of  the  read  and  write  strobes. 
What  is  involved  will  become  apparent 
when  we  discuss  the  interface  board. 

The  Interface 

The  bidirectional  bus  goes  to  invert¬ 
ing  buffers  at  the  controller  end  and 
hence  must  be  inverted  at  the  interface. 
The  74LS240  tristate  buffers  (see  Figure 
1,  page  73)  are  well-suited  for  use  at  the 
interface  end  of  these  lines;  not  only  are 
they  inverting,  but  they  also  supply  (and 
sink)  adequate  current  both  for  the  inter¬ 
connecting  lines  and  for  the  S-100  bus. 

The  controller  imposes  certain  timing 
restrictions  on  the  read  and  write  strobes. 
For  writing  (from  host  to  drive),  data 
must  be  placed  on  the  I/O  bus,  and  the 
write  strobe  must  be  active  for  at  least 
250  ns  and  then  terminated  before  the 
data  on  the  bus  become  inactive.  To 
achieve  these  conditions,  the  write  strobe 
is  generated  by  two  one-shots.  The  first, 
which  has  no  timing  capacitor,  delays  its 
output  by  a  barely  measurable  interval 
before  activating  the  second.  The  second 
one-shot  has  the  duration  of  its  pulse  ad¬ 
justed  by  a  variable  resistor  to  end  just  be¬ 
fore  WRITE/  goes  high,  which  deactivates 
the  data  on  the  bus.  The  best  way  to 
adjust  the  timing  of  the  second  one-shot 
is  to  use  a  two-channel,  triggered -sweep 
oscilloscope.  One  channel  shows  the  level 
of  WRITE/,  the  other  channel  the  output 
of  the  second  one-shot.  In  my  setup, 
with  a  4MHz  Z80  CPU,  the  write  strobe 
pulse  can  be  adjusted  to  lie  barely,  but 
entirely,  within  the  pulse  representing  the 
level  at  WRITE/.  It  is  essential  that  you 
use  a  good  quality  timing  capacitor;  a 
disk  ceramic  would  be  a  poor  choice. 

The  situation  for  the  read  strobe  is 
slightly  different.  The  process  involves 
activating  the  read  strobe,  reading  the 
data,  and  terminating  the  strobe  after  the 
host  has  stopped  reading.  One  way  to 
achieve  this  is  to  note  that,  serendipitous- 
ly,  ADDSEL  and  SINP  overlap  PDBIN. 
The  implementation  of  this  scheme 


should  be  apparent  from  Figure  1. 

The  rest  of  the  schematic  is  quite 
simple.  The  pin  numbers  of  the  ICs  have 
not  been  marked;  choose  them  to  fit  the 
arrangement  of  the  chips  on  the  interface 
board.  Note  that  the  pull-up  resistors 
may  range  from  IK  to  4.7K  and  are  best 
supplied  as  a  resistor  pack.  The  designa¬ 
tion  of  the  lines  at  the  controller  end  is 
taken  from  the  Micropolis  manual. 

The  interface  board  requires  two 
adjacent  ports.  As  shown  in  Figure  1, 
these  ports  have  been  wired  as  7EH  for 
COMMAND/STATUS  and  7FH  for  READ/ 
WRITE  data.  The  actual  port  addresses 
may  be  changed  by  inserting  additional 
inverters  in  the  address  lines.  However, 
the  even  address  must  be  kept  for  COM¬ 
MAND  and  the  odd  one  for  data. 

The  Software 

You  can  determine  the  state  of  the 
Winchester  by  reading  STATUS  on  the 
COMMAND/STATUS  port:  whether  it  is 
busy,  ready  to  transmit  data,  ready  to 
receive  data,  and  so  on  is  determined  by 
the  state  of  the  flags  (see  the  Listing,  page 
74).  In  passing,  I  should  note  that  the 
information  contained  in  the  Micropolis 
manual  is  not  entirely  clear  and  shows 
some  inconsistencies  between  the  text 
and  the  accompanying  flow  charts.  A 
certain  amount  of  experimentation  was 
necessary  before  I  arrived  at  the  software 
included  here.  It  works  but  it  may  not  be 
what  Micropolis  intended ! 

The  Winchester  is  activated  by  the 
transmission  of  a  command  byte,  followed 
by  six  parameter  bytes,  and  then  triggered 
by  one  more  byte  (whose  actual  value  is 
unimportant).  The  manual  mentions  an 
optional  capability  that  enables  you  to 
reread  the  bytes  after  they  are  transmitted 
to  be  sure  that  no  transmission  error  has 
occurred.  (You  certainly  do  not  want  a 
read  command  to  be  misinterpreted  as  a 
write  command ! )  I  experimented  with 
this  and  would  suggest  that  “optional” 
be  replaced  by  “essential.”  It  is  not  clear 
where  the  problem  arises,  but  some  trans¬ 
mission  errors  do  occur;  rereading  is  a 
cheap  form  of  insurance. 

Complete  software  to  run  the  Win¬ 
chester  drive  would  be  difficult  to  present, 
since  you  would  have  to  customize  it  for 
your  own  environment.  The  read/write 
module  I  have  shown  may  be  modified 
easily  and  incorporated  into  any  8080  or 
Z80  system.  The  listing  illustrates  some 
of  the  more  attractive  features  of  the  con¬ 
troller:  buffered  read/write,  automatic 
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track  seek  before  reading/writing,  and 
reading/writing  of  multiple  sectors.  The 
controller  is  also  capable  of  reading  and 
writing  “on  the  fly,”  but  this  requires  a 
much  more  elaborate  interface  board. 

No  timing  measurements  have  been 
made.  However,  I  offer  the  following 
subjective  impression:  I  am  presently 
using  double-density  double-sided  8 -inch 
floppies  in  Qume  drives,  formatted  with 
IK  sectors  and  with  separate  read  and 
write  buffers,  and  the  Winchester  has 
about  the  same  speed  relation  to  my  flop¬ 
pies  as  my  floppies  have  to  single-density 
single -sided  ones. 
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(Listing  begins  on  page  74) 
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Goldman. _ Schematic  of  S— 100  Bus  Winchester  interface. 


Winchester  Listing  (Text  begins  on  page  71) 


TITLE  ’READ /WRITE  MODULE’ 

Basic  read  and  write  routines  -for  the  Micropolis 
Winchester  drive  and  custom  interface  board. 
Written  March  1983  by  Oscar  Goldman 


;  HARDWARE  DEPENDENT  DEFINITIONS 

COMMAND  EQU  7EH  ;  Command/status  port  —  output 

STATUS  EOU  7EH  ;  Command/status  port  —  input 

DATA  EQU  7FH  ;  Bi di rect i onal  data  port 

;  STATUS  MASKS 


IRDY 

EQU 

1 

;  1 

means 

a  character  is  ready  for  the  host 

ORDY 

EQU 

2 

;  1 

means 

the  host  may  send  data  to  the  drive 

HBUSY 

EQU 

16 

;  0 

means 

that  the  drive  is  busy 

DREQ 

EQU 

32 

;  1 

means 

that  drive  is  requesting  data 

ATTN 

EQU 

128 

;  1 

means 

that  the  drive  has  completed  its  task 

COMMAND  CODES 


RDCOM  EQU  4EH  ;  Buffered  read  with  auto  seek  and  retry 

WRCOM  EQU  47H  ;  Same  for  write 

;  MISCELLANEOUS  DEFINITIONS 

FALSE  EQU  0 

TRUE  EQU  NOT  FALSE 

DEBUG  EQU  TRUE  ;  Initial  debugging  is  surely  necessary 

SECT*SIZE  EQU  512  ;  May  be  changed  to  suit  system 

;*******¥******************************************************** 

HARDSREAD: 

;  Read  one  or  more  sectors  into  memory,  starting  at  the 

;  address  stored  in  READ*ADD. 

;  Assumes  that  the  contents  of  READ*AREA  have  been  prepared 

;  before  entry  into  the  routine. 

;  First  send  the  read  command  information  to  COMM. 

MV I  C, RDCOM 

LX  I  H, RE AD* ARE A 

CALL  COMM 

;  Now  do  the  actual  read. 


(Continued  on  page  76) 
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Winchester  Listing 


(Listing  continued,  text  begins  on  page  71) 


LDA 

RDSECTS 

5 

Number  o-f  sectors  to  read 

MOV 

D,  A 

5 

Save  it 

LHLD 

READ* ADD 

5 

Start  storing  it  here 

Rl! 

LX  I 

B,SECT*SIZE 

R10s 

IN 

STATUS 

AN  I 

DREQ+ATTN 

JZ 

R 1 0 

■ 

9 

Wait  -for  things  to  stabil: 

AN  I 

ATTN 

JNZ 

DONESREAD 

5 

Done  it  ATTN  says  so 

Rll: 

5 

Read  one  sector 

IN 

DATA 

5 

Get  a  byte 

MOV 

M,  A 

■ 

9 

Store  it 

INX 

H 

9 

Next  location 

DCX 

B 

MOV 

A,  B 

ORA 

C 

9 

Fi ni shed? 

JNZ 

Rll 

9 

No 

DCR 

D 

JNZ 

Rl 

9 

Next  sector 

DONE*READs 

5 

Finished  with  the  reading 

process;  now 

5 

do  the 

■final  cleanup. 

IF 

DEBUG 

LX  I 

H,READ*AUX 

END  IF 

9 

Save  exit  information  For 

9 

debugging  purposes 

JMP 

HARD*END 

;»*************************************************************** 


HARDSWRITE: 

;  See  the  description  o-f  the  READ  routine. 

MV I  C, WRCOM 

LX  I  H, WRITE*AREA 

CALL  COMM 

:  Now  do  the  actual  write. 


LDA 

WRSECTS 

5 

Number  of  sectors 

to  write 

MOV 

D,  A 

Save 

it 

LHLD 

WRITE*ADD 

5 

Start 

writing  From 

here 

LX  I 

B , SECT * S I ZE 

IN 

STATUS 

AN  I 

DREQ+ATTN 

JZ 

W10 

5 

Wait 

For  things  to 

stabi 1 i ze 

AN  I 

ATTN 

JNZ 

DONESWRITE 

5 

Done 

if  ATTN  says 

so 

76 

604 


Dr.  Dobb’s  Journal,  Number  84,  October  1983 


Write  one  sector 


MOV 

A,  M 

5 

Get  a  byte 

OUT 

DATA 

5 

Write  it 

I  NX 

H 

5 

Next  location 

DCX 

B 

MOV 

A,  B 

ORA 

C 

5 

Fi ni shed? 

JNZ 

Wll 

5 

No 

DCR 

D 

JNZ 

W1 

5 

Next  sector 

DONESWRITE: 

;  Finished  with  the  writing  process;  now 

;  do  the  -final  cleanup. 


IF 

DEBUG 

LX  I 

H, WRITE* AUX 

END  IF 

• 

9 

JMP 

HARBtfEND 

5 

Save  exit  information  -for 
debugging  purposes 


;**********:M**************************************************** 


COMM: 


C0: 


Cl : 


Command  and  parameter  bytes  are  sent  to  the  Winchester 
and  are  immediately  reread. 

Enter  with  the  command  byte  in  the  C  register  and  the 
data  area  pointed  to  by  HL. 


PUSH 

H 

5 

IN 

STATUS 

AN  I 

HBUSY 

JZ 

C0 

MOV 

A,C 

OUT 

COMMAND 

CALL 

HWAIT 

CMP 

C 

JNZ 

C0 

POP 

H 

PUSH 

H 

MV  I 

B,6 

IN 

STATUS 

AN  I 

ORDY 

JZ 

Cl 

5 

MOV 

A,  M 

OUT 

DATA 

5 

CALL 

HWAIT 

*  5 

Save  -for  emergencies 


Wait  for  not  busy 
Bet  the  command 
Send  it 

Wait  and  reread 

Bad  reread  —  start  over 
Get  it  back 
Save  it  once  more 
6  parameter  byte 


Wait  for  permission  to  send 

Send  out  one  parameter 
As  before 


(Continued  on  next  page) 
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Winchester  Listing  (Listing  continued,  text  begins  on  page  71) 


CMP 

M 

JNZ 

C0 

5 

Bad  reread  -  start  anew 

INX 

H 

5 

Next  parameter 

DCR 

B 

JNZ 

Cl 

9 

Continue 

IN 

STATUS 

AN  I 

ORDY 

JZ 

C2 

OUT 

DATA 

9 

This  is  the  ’GO'  byte 

POP 

H 

9 

Don't  ness  with  the  stack 

RET 

m 

9 

A1 1  done 

HWAIT: 

;  Wait,  reread  the  last  byte  sent 

;  and  return  it  in  the  A  register. 


HW0: 

IN 

STATUS 

AN  I 

ORDY 

JNZ 

HW0 

HW1: 

IN 

STATUS 

AN  I 

IRDY 

JZ 

HW1 

IN 

RET 

DATA 

;  Wait  -for  not  ready 


;  Wait  -for  character  to  be  available 
;  Read  it 


•  **************************************************************** 


HARDSEND: 

;  All  Winchester  accesses  end  with  this  routine. 

;  The  'termination'  byte  is  returned  in  the  E  register, 

;  and  optionally,  13  auxiliary  in-formation  bytes 

;  useful  -for  debugging,  are  stored  in  the  data  area 

;  pointed  to  by  HL. 


E0: 

IN 

STATUS 

AN  I 

HBUSY 

JZ 

E0 

5 

Wait  for  the  dust  to 

Els 

IN 

STATUS 

AN  I 

IRDY 

JZ 

El 

5 

Wait  for  a  character 

IN 

DATA 

■ 

9 

Get  it 

MOV 

E,A 

9 

and  store  it 

IF 

DEBUG 

MV  I 

B,  13 

9 

13  aux  bytes 

E2: 

IN 

STATUS 

AN  I 

IRDY 

JZ 

E2 

9 

Wait  for  a  character 

IN 

DATA 

5 

Get  it 
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MOV  M,A  ;  and  store  it 

I NX  H  ;  Next  one 

DCR  B 

JNZ  E2  ;  Loop  til  done 

END  IF 

RET 

;************************************¥*************************** 

;  DATA  AREA 

READ* AREA 

;  6  byte  parameter  area  -for  read  routine 


RHEAD  DS 
RTRACK  DS 
RSECT  DS 
RDSECTS  DS 
DB 


l&fhead  number 
2  bytes  -For  track 
Starting  sector  number 
Number  o-f  sectors  to  read 
Value  doesn’t  matter  -for  read 


READ*ADD 


;  Address  to  read  to 


WRITE* AREA 

;  6  byte  parameter  area  -For  write  routine 


WHEAD  DS 
WTRACK  DS 
WSECT  DS 
WRSECTS  DS 
DB 


l£*head  number 
2  bytes  For  track 
Starting  sector  number 
Number  oF  sectors  to  write 
Value  doesn’t  matter  For  write 


WRITE* ADD 
DS 


;  Address  to  write  From 


IF 

READ*AUX 

DS 

WRITE*AUX 

DS 

END  IF 


DEBUG 


End  Listing 


80 
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Using  The  Epson 
Bit  Plot  Graphics 


The  Epson  series  of  printers  has  been 
very  popular,  partly  because  of  the 
variety  of  things  they  can  do  besides 
ordinary  printing.  One  of  the  options  for 
the  MX-80  is  the  GRAFTRAX  ROM, 
which  gives  the  Epson  a  dot-level  graphics 
capability.  While  this  sounds  like  a  power¬ 
ful  feature,  it  is  not  really  all  that  easy  to 
use,  particularly  since  the  MX-80  has  no 
reverse  line-feed  command.  Still  it  is 
possible,  with  a  little  patience,  to  get  the 
printer  to  do  some  nice  work. 

This  article  describes  how  I  used  the 
Epson  MX-80  to  print  electron  density 
maps  of  the  hydrogen  atom.  The  calcula¬ 
tions  involved  would  keep  most  physics 
students  busy  for  quite  a  while  and  would 
take  those  unfamiliar  with  the  Schrodinger 
Wave  Equation  even  longer.  Therefore, 
this  article  does  not  set  out  to  rigorously 
explain  or  solve  the  Schrodinger  equa¬ 
tion;  many  thorough  treatments  exist 
elsewhere  and  the  particular  forms  of  the 
equation  I  used  may  be  found  in  the  cited 
references.  What  I  wish  to  present  is  the 
way  in  which  I  used  the  bit-plot  graphics 
to  represent  the  solutions. 

The  Problem 

Most  people  are  familiar  with  the 
basic  structure  of  the  atom:  a  central 
nucleus  that  is  surrounded  by  “  orbiting” 
electrons.  The  electrons  are  actually  bet¬ 
ter  described  as  a  “cloud”  because  their 
exact  positions  can  never  be  determined 
due  to  the  Uncertainty  Principle.  What  we 
can  calculate,  however,  is  the  probability 
that  an  electron  will  be  found  in  a  partic¬ 
ular  region  surrounding  the  atom.  Many 
texts  have  “pictures”  showing  this  elec¬ 
tron  cloud  for  the  hydrogen  atom  (the 
only  atom  that  is  completely  solvable)  at 
different  energy  levels. 

I  wanted  to  be  able  to  produce  this 
type  of  electron  density  map.  It  seemed 
natural  to  break  the  problem  into  two 
parts:  first  calculating  all  the  probability 
densities  for  a  particular  energy  level  and 
then  using  these  values  to  produce  the 
electron  density  map.  The  two  programs 
HYDROGEN  and  HPLOT,  which  are 
written  in  Microsoft  BASIC -80,  achieve 
these  two  goals,  respectively. 


by  Don  Gay 


Don  Gay,  Beulah  College,  P.O.Box  16, 
Nuku’alofa,  Tonga. 


The  Program 

The  electron  density  map  can  be 
visualized  as  a  grid  of  small  probability 
cells  with  the  nucleus  at  the  origin  (0,0). 
For  each  cell  surrounding  the  nucleus  a 
probability  density  is  calculated.  When 
the  cell  is  printed  its  “darkness”  is  pro¬ 
portional  to  the  probability  at  that  point. 
Luckily,  the  plots  are  always  symmetrical 
about  the  x  and  y  axes  so  the  cells  need  to 
be  evaluated  for  only  one  quadrant;  the 
other  quadrants  are  obtained  by  simple 
reflection.  Program  HYDROGEN  (Listing 
One,  page  86)  solves  the  Schrodinger 
equation  and  calculates  the  probability 
density  at  each  (x,y)  position.  The  pro¬ 
gram  is  written  below  in  pseudo-code. 

Input  N,L,M; 

Input  scale  factors; 

Open  output  data  file; 

Output  scale  factors; 

For  each  (x,y)  coordinate  { 

calculate  probability  density; 

convert  to  an  ASCII  character; 

write  character  to  file; 

* 

Write  highest  probability  obtained  to  file; 
End. 

The  numbers  N,  L,  and  M  are  the 
three  principal  quantum  numbers  that  de¬ 
termine  which  energy  level  the  atom 
is  in.  These  cannot  be  arbitrary  but 
must  conform  to  the  following  values: 
N  =  1 . .  MAX,  L  <  N,  M  <=  L.  All  three 
must  be  integers.  The  value  of  MAX  in 
this  program  is  9,  due  to  the  way  in  which 
the  output  data  filename  is  generated 
automatically  from  the  values  of  N,  L, 
and  M. 

Two  scale  factors  are  required.  One  is 
the  maximum  distance  from  the  nucleus 
that  you  want  to  be  calculated  (RSCALE); 
this  is  in  units  of  the  Bohr  radius,  a  useful 
unit  in  atomic  measurements  (  ~  5.3E-10 
meters).  The  other  is  the  maximum  prob¬ 
ability  density  calculated  in  that  plot. 
These  factors  are  determined  largely  by 
trial  and  error.  The  program  simplifies 
this  task  by  printing  at  the  end  of  a  run 
the  maximum  probability  calculated. 
Using  this  value  as  PSCALE,  you  can 
easily  find  the  value  of  RSCALE  so  that 
the  display  starts  at  the  edge  of  the  speci¬ 
fied  grid.  Table  I  (page  84)  shows  some 
values  of  RSCALE  and  PSCALE. 

As  the  probability  density  for  each 
cell  in  the  positive  quadrant  is  calculated, 
it  is  scaled  to  a  relative  value  between  1 
and  25  and  converted  to  an  ASCII  charac¬ 


ter  (A=l  and  Y=25).  These  are  printed 
out  on  the  console  device  as  they  are  cal¬ 
culated,  as  well  as  being  written  to  the 
disk  file,  which  makes  it  possible  to  see 
the  progress  of  the  calculation. 

Figure  1  (page  84)  shows  a  sample 
of  the  data  file  that  HYDROGEN  pro¬ 
duces.  Only  the  positive  quadrant  is  pres¬ 
ent  (compare  this  to  the  resulting  bit  plot 
in  Figure  3  on  page  85).  The  two  values 
on  the  first  line  are  RSCALE  and  PSCALE, 
respectively,  and  the  number  on  the  last 
line  is  the  maximum  probability  calcu¬ 
lated  for  that  particular  graph.  The  letter 
at  the  bottom  left  corner  represents  the 
origin,  the  left-hand  column  is  the  posi¬ 
tive  y  axis,  and  the  bottom  row  is  the 
positive  x  axis  of  the  grid. 


Plotting  the  Data 

The  program  HPLOT  (Listing  Two, 
page  92)  takes  as  its  input  the  data  file 
created  by  HYDROGEN.  It  then  prints 
out  for  each  cell  position  on  the  entire 
grid  a  cell  of  dots  whose  darkness  is  pro¬ 
portional  to  the  calculated  probability 
density.  At  this  stage  we  are  dealing  with 
only  25  different  probability  values, 
represented  by  the  letters  A  -Y.  Each  cell 
comprises  a  matrix  of  dots  with  seven 
columns  and  eight  rows;  this  is  very  nearly 
a  square  on  the  MX-80.  Varying  the  num¬ 
ber  of  dots  printed  in  each  cell  for  each 
probability  density  produces  a  cloud-like 
diagram.  A  dark  cell  contains  many  dots 
and  corresponds  to  a  high  probability 
density,  while  a  space  or  a  light  cell  with 
only  a  few  dots  corresponds  to  a  low 
probability  density. 

The  Epson  MX-80  printer  has  nine 
print  needles  in  the  print  head,  eight  of 
which  can  be  individually  controlled.  In 
the  bit  plot  mode,  you  can  instruct  the 
printer  to  print  up  to  480  dots  per  line  by 
sending  an  escape  sequence  that  tells  the 
printer  how  many  of  the  next  characters 
are  to  be  interpreted  as  bit  graphics  data. 
As  each  character  is  sent  to  the  printer, 
there  is  a  direct  mapping  between  the  bi¬ 
nary  one’s  in  the  character  and  the  print 
needles  that  fire. 

For  each  cell  that  is  printed,  seven 
numbers,  corresponding  to  the  seven 
columns  in  the  cell,  must  be  sent  to  the 
printer.  As  each  number  is  sent,  one 
column  of  eight  vertical  dots  is  printed. 
The  listing  of  HPLOT  shows  the  specific 
codes  required  to  print  in  the  bit  graphics 
mode.  Note  also  that  the  line  spacing  is 
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changed  so  that  adjacent  lines  touch  each 
other  to  produce  a  smooth  display. 

1  worked  out  the  data  needed  for  the 
25  different  cells  on  graph  paper  by  fill¬ 
ing  in  progressively  more  dots  in  each 
cell.  The  lightest  cell  is  a  space  and  each 
of  the  other  cells  has  two  more  dots  than 
the  preceding  one;  the  cell  corresponding 
to  the  letter  Y  therefore  has  48  dots. 
After  plotting  each  cell  on  graph  paper, 
I  read  the  seven  numbers  required  for 
each  cell  from  the  seven  corresponding 
columns  by  designating  a  dot  as  one  and 
a  space  as  zero  and  reading  the  equivalent 
binary  number.  I  found  it  quite  difficult 
to  produce  a  homogeneous  looking  cell 
for  certain  values,  and  some  still  have 
room  for  improvement.  An  example  of 
this  process  is  shown  in  Figure  2  (page 
84).  The  x’s  in  the  graph  image  represent 
dots  that  are  to  be  present.  The  periods 
indicate  that  no  dot  is  to  be  printed.  By 
reading  down  the  vertical  columns  in  the 
binary  image  you  can  see  that  the  seven 
numbers  required  (in  hex)  are: 

AA,5D,AA,77,AA,5D,AA 

The  data  for  the  other  letters  can 
be  seen  in  Listing  Two.  All  these  values 
are  stored  in  an  array,  and  the  appropriate 
set  of  seven  numbers  to  be  sent  to  the 
printer  is  selected  depending  on  the 
character  (probability  density)  that  is  to 
be  represented. 

As  HPLOT  reads  in  the  ASCII  data 
file,  it  creates  the  full  string  image  of  the 
positive  quadrant  in  memory.  When  plot¬ 
ting  the  other  quadrants  it  simply  takes 
the  appropriate  values  that  are  stored  in 
the  positive  quadrant.  The  size  of  the  grid 
is  from  -30  to  +30  cells  in  the  x  and  y 
direction.  The  scaled  distance,  however, 
not  the  cell  number,  is  printed  on  the 
graph  axis. 

I  should  also  point  out  that,  if  the 
value  of  PSCALE  you  chose  is  smaller 
than  the  maximum  probability  calculated, 
the  character  @  will  appear  in  the  data 
file.  This  signifies  an  overflow  and  you 
should  choose  a  larger  value  for  PSCALE 
before  attempting  to  plot  the  data.  By 
varying  RSCALE  you  can  look  at  magni¬ 
fied  views  of  the  central  portion  if 
needed. 

The  number  of  calculations  involved 
in  both  programs  keeps  the  interpreter 
very  busy  indeed.  In  fact,  when  I  first 
wrote  the  program  using  all  single - 
precision  variables  for  loop  indexes,  it 
took  about  20  minutes  to  generate  the 
data  and  as  long  again  to  print  it  out  (2 
MHz  Z80).  Since  I  have  changed  the  vari¬ 
ables  to  integers  where  possible,  it  now 
takes  (depending  on  N,L,M)  about  8-15 
minutes  to  generate  the  data  and  about 
the  same  to  print  it  out.  I  have  also  com¬ 
piled  the  program  using  BASCOM,  which 
enables  both  HYDROGEN  and  HPLOT 
to  run  approximately  twice  as  fast.  One 
thing  the  program  seems  to  do  quickly  is 
use  up  ribbons  on  the  printer! 


Although  the  actual  mathematics  for 
obtaining  the  data  are  complex,  the  tech¬ 
nique  for  representing  the  data  with  dif¬ 
ferent  density  cells  is  quite  general  and 
could  be  applied  to  many  different  situa¬ 
tions.  One  way  of  possibly  speeding  up 
HPLOT  would  be  to  convert  all  the  input 
string  data  to  an  integer  array  that  would 
contain  the  direct  index  into  the  dot 
graphics  data  array  G%().  This  would 
require  less  decoding  than  the  present 
scheme,  but  I  haven’t  bothered  to  make 
the  change  at  this  stage. 

The  references  below  give  the  formu¬ 
lae  required  for  the  solution  of  the  Schro- 
dinger  equation  for  the  hydrogen  atom. 
Comments  in  the  listing  of  HYDROGEN 
show  where  I  obtained  each  formula. 
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Table  I 

Scale  factors  for  different  N,  L,  M  combinations. 


NjL^M 

1,0,0 

2,0,0 

2,1,0 

2,1,1 

3,0,0 

3,1,0 

3.1.1 
3,2,0 
3,2,  1 

3.2.2 


RSCALE 

PSCALE 

RSCALE 

PSCALE 

4.4 

0.271 

4.0,0 

45 

0.033 

13.5 

0.096 

4,1,0 

44 

0.096 

12 

0.295 

4,1,1! 

44 

0.048 

12 

0.  147 

4,2,0 

42 

0.  163 

27 

0.051 

4,2,1 

36 

0.061 

26 

0.  153 

4,2,2 

42 

0.061 

26 

0.078 

4,3,0 

37 

0.245 

23 

0.268 

4,3,1 

35 

0.087 

20 

0.  100 

5,2,0 

63 

0.  118 

23 

0.  101 

5,2,  1 

56 

0.043 
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N,L,M  =  3,2,  1 

Maximum  probability  density 


20 . 00- 


16. 00- 


12.00- 


0.  00- 


-4.00- 


-8.00- 


-12.  00- 


-16.00- 


-20.00- 


I  I  I  I  I  I  I  I  I  I  I 

-20.00  -16.00  -12.00  -8.00  -4.00  0.00  4.00  8.00  12.00  16.00  20.00 

Distance  -from  nucleus  in  E<ohr  Radii. 


Figure  3. 

Electron  density  map  for  the  hydrogen  atom. 
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Epson  Graphics  (Text  begins  on  page  82) 

Listing  One 


_ _ 

i 

i 

—  HYDROGEN  — 

i 

i 

This  program  solves  the  schrodinger  equation  ! 
-for  the  Hydrogen  atom  and  produces  a  data  -file  ! 
which  is  used  to  plot  a  2-D  electron  density  ! 
map  -for  the  hydrogen  atom.  • 

I 

I 

Written  in  Microsoft  BASIC-80  Version  5.2 

I 

• 

Program  Author:  Don  Gay  » 

Last  Revision  :  June  7,  1983  ! 


1000 
1010 
1020 
1030 
1040 
1050 
1060 
1070  7 
1080  7 
1090  7 
1100  7 
1110  ' 

1120  7 
1130  7 
1140  ' 

2000  ’ 

2010  7 
2020  SIZE’/.  =20 
2030  CELLS7.=30 
2040  7 

2050  7 - Reserve  space  -for 

2060  7 

2070  DIM  F<20> 

2080  DIM  C (20, 20) 

2090  DIM  P (20) 

2100  7 

2110  7 - Detine  Constants. 

2120  7 

2130  PI =3. 14159 
2140  R0W*=STRING$<31,32> 

2150  7 

2160  7 - Calculate 

2170  7 
2180  F (0) =1 

2190  FOR  17.=  I  TO  SIZE7. 

2200  F<I7.)=F(I7.-1)  *17. 

2210  NEXT  17. 

2220  7 


’Size  of  factorial  arrays. 
7  No.  of  cells  in  grid  axis 

variables. 

7  Factorial s 
’Combinational  Array 
’Coefficients  of  Legendre 
. .  pol ynomi al 


’Initialize  to  31  spaces 


Factor l al s 


2230  7 - Calculate  combinations. 

2240  7 

2250  FOR  I7.=0  TO  SIZE’/. 

2260  C  (  1 7. ,  0  )  =  1 

2270  FOR  J7.=  l  TO  17. 

2280  C(I7.,  J7.)=F(I7.)  /  (F(J7.)  *F(I7.-J7.)  ) 

2290  NEXT  J7. 

2300  NEXT  17. 

2310  7 

2320  7 - Get  Quantum  numbers  &  scale  factors. 

2330  7 

2340  PRINT  CHR*<27) ; "C"  ’Clear  screen. 

2350  PRINT  TAB (24);“ —  HYDROGEN  — PRINT: PRINT 
2360  INPUT  "Enter  values  for  N,L,M  :  " ,  N7.,  L7.,  M7. 

2370  IF  N7.<=9  AND  L7.<N7.  AND  M7.<=L%  GOTO  2375 
2374  PRINT  "Invalid  entry,  try  agai n . " : GOTO  2360 
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2375  ’Form  a  3  digit  string  from  n,l,m  -for  -filename 
2380  NLM*=MID*  (STR*  (N7.*100+L7.*10+M7.)  ,2,3) 

2390  FILE*="HPLOT"+NLM*+"  .  DAT" 

2400  INPUT  "Enter  the  radial  scale  factor  :  "  , RSCALE 
2410  INPUT  "Enter  the  probability  scale  factor  : " , PSCALE 


2420  ’ 

2430  ’ -  Evaluate  constant  term  for  this  n,l,m  choice 

2440  C1=SQR  (  (24L7.+  1 )  *F  (L7.-M7.)  /  (2*F  (L7.+M7.)  )  ) 

2450  ’ 

2460  ’ - Store  coefficients  of  Legendre  polynomial 

2470  ’ 

2480  ’  -  first  do  special  case  Plm(0) 

2485  ’  (see  Ref.  4,  pg  334,  eqn  8.6.1) 


2490  GARG= (LX+M7+1 ) /2  ’Gamma  function  argument 

2500  GOSUB  4000: GAM 1=GAMMA  ’Calculate  Gamma  function 

2510  GARG=(L7.-M7.) /2+1 
2520  GOSUB  4000:  GAM2=GAMMA 

2530  P0=2'  M7./SQR(PI  >  *COS(  (L7.+M7.)  *PI/2)  *GAM1/GAM2 
2540  ’  —  now  do  all  other  coefficients  of 

2545  ’  ..  polynomial  in  cos(theta) 

2550  ’  (see  Ref.  3,  pg  2580,  eqn  11.19,11.20) 

2560  FOR  I7.=0  TO  INT  (  (L7.-M7.) /2) 

2570  P(L7.-M7.-2*I7.)  =  (-1)A(M7.+  I7.)  *C1*F(2*  (L7.-I7.)  )  / 

(2"'L7.*F  ( 17.)  *F  (L7.-I7.)  *F  (L7.-M7. -2*  17.)  ) 


2580 

2590 

2600 

2610 

2620 

2630 

2640 

2650 

2660 

2670 

2675 

2680 

2685 

2690 

2700 

2710 

2720 

2730 

2740 

2750 

2760 

2770 

2780 

2790 

2800 

3000 

3010 

3020 

3030 


NEXT  17. 

r 

OPEN  "0",#1,FILE* 

PRINT  # 1 , RSCALE , PSCALE 

y 

MAX.P=0  ’Maximum  probability  density  for  this  n,l,m 
FOR  Y7.=CELLS7.  TO  0  STEP  -1 
FOR  X7.=0  TO  CELLS7. 

XPOS=RSCALE*X7./CELLS7.:  YP0S=RSCALE*Y7./CELLS7. 
GOSUB  3000  ’Calculate  prob.  density 

’Remember  maximum  probability 
IF  PROB>MAX.P  THEN  MAX.P=PROB 
’Scale  probability 

P=CINT(PR0B/PSCALE*24) +1 : IF  P>25  THEN  P=0 
MID*  (ROW*,  X7.+  1 ,  1  )=CHR*  (P+64) 

PRINT  CHR*(P+64);  ’Show  on  console 

NEXT  XX 

PRINT  "  Y7.:  PRINT  #l,ROW* 

NEXT  Y7. 

PRINT  #1 , MAX . P 
CLOSE  #1 

PRINT  "Function  complete  for  " ;FILE* 

PRINT  "Maximum  probability  density  is" ;MAX.P 
END 


’ - Subroutine  to  calculate  probability  density 

GOTO  3150 

’  Needs  :  (Continued  on  page  90 j 
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Epson  Graphics  (Listing  continued,  text  begins  on  page  82) 

Listing  One 


3035 

7 

XPOS, YPOS 

= 

coordinates  ot  required  point 

3040 

7 

N7.,L7.,M7. 

= 

principal  quantum  numbers 

3050 

7 

F  (n) 

= 

n  ! 

3060 

y 

C (n, r ) 

= 

n  !  /  (r  !  (n-r)  !) 

3070 

y 

Cl 

= 

constant  term  tor  spherical  harmonics 

3080 

y 

P0 

= 

Legendre  polynomial  Plm(0)  special  case 

3090 

y 

P  (n ) 

= 

Coetticients  ot  Legendre  polynomial 

3100 

7 

PI 

= 

3. 14159 

3110 

y 

3120  ’  Returns  : PROB  =  Probability  density 

3130  ’ 

3140  ’ -  Evaluate  constant  terms  tor  this  x,y 

3150  IF  XP0SC1E-5  THEN  THETA=PI/2  ELSE  THETA=ATN ( YPOS/XPOS) 
3155  ’Convert  to  spherical  coordinates. 

3160  R=SQR(XPOS*XPOS+YPOS*YPOS) 

3170  S I NE=S I N  < THET A )  :  COSINE=COS (THETA) 

3180  LA=2*R/NX  ’Argument  tor  Laguerre  polynomial 

3190  ’ -  Calculate  Laguerre  polynomial  (Ret.  2,  pg  216) 

3200  LGR=0 

3210  FOR  I7.=0  TO  Ny.-L7.-1 

3220  LGR=LGR+  (-1 )  ^I7.*C  (N7.+L7.,  N7.-L7.-I7.-l )  *LA~I7./F  (17.) 

3230  NEXT  17. 

3240  ’ -  Calculate  Radial  tunction  (Ret.  1,  pg  91) 

3250  RAD=SQR  (F  (N7.-L7.-l  )  /  (2*N7.*F  (N7.+L7.)  )  )  * 

(2/N7.) ~  (L7.+  1 . 5)  *R  XL7.*EXP  (-R/N7.)  *LGR 

3260  ’ -  Calculate  Spherical  Harmonics  (Ret.  1,  pg  75) 

3270  ’It  cos ( theta ) =0  or  1  then  use  special  tormula. 

3275  ’  (see  Ret.  4,  pg  334) 

3280  IF  COSINE=0  THEN  YSP=C1 *P0: GOTO  3340 
3290  IF  SINE=0  AND  M7.<  >0  THEN  YSP=0:GOTO  3340 
3300  YSP=0 

3310  FOR  I7.=0  TO  L7.-M7.:  YSP=YSP+P  (17.)  *C0SINEX  I7.:  NEXT  17. 

3320  IF  M7.=0  THEN  3340 
3330  YSP=YSP*  (-1 )  ''M7.*SINE'NM7. 

3340  PROB=R*R*RAD*RAD*YSP*YSP 
3350  RETURN 


3360 

4000 

4010 

4020 

4030 

4035 

4040 

4050 

4060 

4070 

4080 

4090 

4100 

4110 

4120 

4130 

4140 

4150 


’ - Subroutine  to  calculate  the  Gamma  tunction 

GOTO  4090 

r 

’  Needs: 

’  PI  =  3. 14159 

’  F (n )  =  n! 

GARG  =  Argument  must  be  integer  or  halt-integer  >  0 

7 

’  Returns  GAMMA  =  GAMMA (GARG) 


IF  GARG=INT (GARG)  THEN  Z=F (GARG- 1 ): GOTO  4150 
GAMMA= 1 

FOR  I7.=  l  TO  2t  (GARG— 1 )  STEP  2 
GAMMA=GAMMA*I7. 

NEXT  17. 

GAMMA=GAMMA*SQR(2*PI ) / (2""GARG) 

RETURN 


End  Listing  One 


90 


Di.  Dobb’s  Journal,  Number  84,  October  1983 


Listing  Two 


1000  ’ 

1010  ’ 

1020  ’ 

1030  ’ 

1040  ’ 

1050  ’ 

1060  ’ 

1070  ’ 

1080  ’ 

1090  ’ 

1100  ' 

1110  ’ 

1120  ' 

1130  ’ 

1140  ’ 

2000  ’ 

2020  ’ -  Reserve  space  for  some  variables. 

2025  ’ 


—  HPLOT  — 

This  program  plots  data  generated  by  the  program 
HYDROGEN  for  the  electron  distribution  around  a 
hydrogen  nucleus  for  different  N,L,M. 

Written  in  Microsoft  BASIC-80  Version  5.2 
Requires  an  EPSON  MX-80  printer  with  GRAFTRAX. 

Program  Author  :  Don  Gay 
Last  revision  :  June  7,  1983 


2030 

2040 

2045 

2050 

2055 

2060 

2065 

2070 

2080 

2085 

2090 

2100 

2110 

2120 

2130 

2140 

2150 

2160 

2170 

2180 

2185 

2190 

2195 

2200 

2210 

2220 

2230 

2240 

2250 

2260 

2270 

2280 

2290 

2300 

2310 

2315 


DIM  ROW* (30)  ’Ascii  data  for  each  row 

DIM  GX(25,7)  ’Graphics  data  for  each  cell 

y 

’ -  Define  constants. 

CELLS=30  ’No.  of  cells  on  each  axis 

C17.=  1:C647.=64 


’ - Read  bit  graphics  data 

r 

FOR  I7.=  l  TO  25 

FOR  J7.=  l  TO  7 

READ  G7.(I7.,J7.) 

NEXT  J7. 

NEXT  17. 

9 

WIDTH  LPRINT  255  ’Inhibit  auto  CRLF  on  printer 

PRINT  CHR* (27) ; "C"  ’Clear  screen 

PRINT  TAB (22) ; " —  HPLOT  — PRINT: PRINT 
PRINT  "You  may  select  to  plot  the  electron  “ ; 

PRINT  "configuration  for  different" 

PRINT  "values  of  n,  1  and  m,  the  principal 
PRINT  "quantum  numbers. PRINT 

PRINT  "e.g.  If  you  want  a  plot  of  n=2 ,  1=1,  m=0  then  " 

PRINT  "enter  the  string  ’ 210’ PRINT 

INPUT  "Enter  the  3  numbers  for  n,l,m  :  " , NLM* 

IF  LEN(NLM*)<>3  GOTO  2220 
F I LE*= " HPLOT " +NLM*+ " . DAT" 

OPEN  " I " , #1 , FILE*  ’Get  data  file. 

I NPLIT  #  1 ,  RSCALE ,  PSCALE 
FOR  I7.=CELLS  TO  0  STEP  -1 
INPUT  #1,  ROW*  (17.) 

NEXT  17. 

CLOSE  #1: PRINT 

PRINT  "Press  <cr>  when  the  printer  is  ready  : “ ; 

C*=  INPUT*  (  1  )  (Continued  on  page  94) 
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Epson  Graphics  (Listing  continued,  text  begins  on  page  82) 

Listing  Two 


2320 

2325 

2330 

2340 

2345 

2350 

2360 

2370 

2380 

2390 

2400 

2410 

2415 

2420 

2430 

2440 

2450 

2460 

2470 

2480 

2490 

2500 

2510 

2520 

2530 

2540 

2550 

2560 

2570 

2580 

2584 

2585 
2590 
2595 
2600 
2610 
2620 
2625 
2630 
2640 
2650 
2660 
2670 
2675 
2680 
2685 
2690 
2700 
2710 
2720 
3000 
3010 
3020 
3030 


LPRINT  TAB (17); 

LPRINT  "Electron  density  map  tor  the  hydrogen  atom." 
LPRINT  TAB (17) ; STRING* (43, 45) : LPRINT: LPRINT 
LPRINT  " N , L , M  =  " ; MID* (NLM*, 1 , 1 )  ;  "  ,  " ; 

LPRINT  M I D* ( NLM* , 2 , 1 ) ; " , " ; MID* (NLM*, 3, 1) 

LPRINT  "Maximum  probability  density  =  “ ; PSCALE 
LPRINT: LPRINT 

LPRINT  CHR* (27) ; "3" ; CHR* (24) ; ’ Set  close  line  spacing. 
GOSUB  2670  ’Print  x  axis  scale. 

FOR  Y*/.=CELLS  TO  -CELLS  STEP  -1 

IF  Yy./6<>INT(Y7./6)  THEN  LPRINT  "  " ;  :  GOTO  2420 

LPRINT  USING  "###.##";  RSCALE*Y7./ CELLS ;:  LPRINT 
’Set  printer  to  bit  plot  mode,  427  dots. 

LPRINT  CHR* (27) ; "K" ; CHR* ( 1 71 ) ; CHR* ( 1 )  ; 

FOR  X7.=— CELLS  TO  CELLS 

P7.=ASC  ( M I D*  ( ROW*  ( ABS  ( Y7. )  )  ,  ABS  (X7.)  +C17.,C1 7. )  )  -C647. 
FOR  C7.=  l  TO  7 

LPR I  NT  CHR*  ( G7.  (  P7. ,  C7. )  )  ; 

NEXT  C7. 

NEXT  X7. 

IF  YX/6=INT(Y7./6)  THEN  LPRINT 
LPRINT 
NEXT  Y7. 

GOSUB  2670  ’Print  X  axis  scale. 

LPRINT: LPRINT  "  " ; 

FOR  X=— CELLS  TO  CELLS  STEP  6  ’  . .  and  numbers 

LPRINT  USING  "###.##  "; RSCALEtX /CELLS; 

NEXT  X 

LPRINT  CHR* (27) ; "3" ;  ’Reset  printer. 

LPRINT: LPRINT  TAB (23); 

LPRINT  "Distance  trom  nucleus  in  Bohr  Radii." 

LPRINT  STRING* (12, 10)  ’Form  teed 

PRINT  "Would  you  like  to  print  this  out  again"; 

INPUT  "(Y/N)  ?  " , A* 

IF  A*="Y"  GOTO  2310 
IF  A*<  >"N"  GOTO  2590 

PRINT  "Would  you  like  to  plot  a  ditterent  configuration"; 
INPUT  "(Y/N)  ?  " , A* 

IF  A*= ” Y "  GOTO  2160 
IF  A*<  >"N"  GOTO  2620 
PRINT  CHR* (27) ; "C" 

END 


’ - Subroutine  to  print  x  axis  scale. 

’Set  printer  to  bit— plot  mode,  462  dots. 

LPRINT  "  " ; CHR* ( 27 ) ; " K " ; CHR* ( 206 ) ; CHR* ( 1 > ; 
’Print  vertical  bars  on  axis 


FOR  I7.=  l  TO  11 

LPRINT  STRING* (41 , 0) ; CHR* (255)  ; 
NEXT  17.:  LPRINT 
RETURN 


’  Bit  graphics  data  for  480  dots  per  line 

y 

’  Each  pixel  is  7  columns  X  8  rows  (approx,  square) 
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3040  7 
3050  DATA 
3060  DATA 
3070  DATA 
3080  DATA 
3090  DATA 
3100  DATA 
3110  DATA 
3120  DATA 
3130  DATA 
3140  DATA 
3150  DATA 
3160  DATA 
3170  DATA 
3180  DATA 
3190  DATA 
3200  DATA 
3210  DATA 
3220  DATA 
3230  DATA 
3240  DATA 
3250  DATA 
3260  DATA 
3270  DATA 
3280  DATA 
3290  DATA 


ScH00,  ScH00,  8cH00,  8cH00,  8cH00,  ScH00,  ScH00 
ScH00,  ScH00,  ScH20 ,  8cH00,  ScH04,  8cH00,  8cH00 
S<H02  ,  8cH00 ,  ScH20  ,  ScH00  ,  8cH04 ,  8cH00 , 8.H40 
ScH40 ,  ScH02  ,  8cH08 ,  8cH00 ,  ScH  1 0 ,  8cH40 ,  ScH02 
SeH04 ,  &H40  ,  ScH  1 0 ,  ScH02  ,  ScH80 ,  ScH08 ,  8cH2 1 
ScH24 ,  ScH80 ,  ScH  1 2 ,  ScH40 ,  ScH04 ,  ScH  1 0 ,  8cH4 1 
&H42 , ScH08 , ScH22 , ScH84 ,  ScH  1 1 , 8cH40 , ScH 1 2 
8cH88 ,  8cH22  ,  ScH48 ,  ScH25 ,  ScH80 ,  8cH  1 2 ,  8cH48 
8cH51 ,  ScH04, 8cHA2,  8cH08,  ScH55,  8cH20,  ScH8A 
ScH92 ,  ScH24 ,  ScH49  ,  SeH92 ,  ScH24 ,  8cH49 ,  ScH92 
ScH88  ,  ScH55 ,  8cH02 , ScHA9  ,  8cH04 ,  ScHAA ,  8cH55 
ScH42 ,  ScHAD ,  8cH32 ,  8cHC8 ,  ScH  1 2 , ScHB9  ,  ScH24 
ScHAA,  3cH41 ,  8cH36,  ScHC9, 8cH22,  8cH55,  8cHAA 
ScH55 ,  ScHA2  ,  &H55 ,  ScHAA  ,  8cH55 ,  8cH8A ,  8cH55 
8cH55, ScHAA,  8cH55, ScHAA, 8cH55, ScHAA, ScH55 
ScHAA,  8cH55,  ScHAA,  ScH77,  ScHAA,  8cH55,  8cHAA 
ScHAA ,  ScH5D  ,  ScHAA ,  ScH77 ,  ScHAA ,  ScH5D ,  ScHAA 
8cHD  A ,  3cH2D  ,  ScHD7  ,  8cHB7  ,  8cH6B ,  8cHB4 , ScH5B 
ScHB6,  ScH6B,  ScHDA,  8cHB6,  ScH5B,  8cHED,  ScH56 
ScHDB , 8cH6D , ScHB6 , 8cHDB , 8cH6D , ScHB6 , ScHDB 
ScH6  A ,  ScHDF ,  8cHB5 ,  8cH6F ,  ScHEA ,  8cH9  A ,  ScHD5 
ScHEE ,  ScHBB ,  8cH77 ,  ScHBE ,  ScHDD ,  ScH77  ,  ScHDD 
8cH5D  ,  ScHFF ,  ScHFA ,  ScHDF ,  ScH77 ,  ScHFE  ,  ScHAB 
ScHEF ,  ScHDD  ,  ScH77 ,  ScHFF ,  ScHDE,  ScH7B,  ScHEF 
S<HDF ,  ScHFB ,  8cH7F ,  ScHED ,  ScHFF ,  ScHBE ,  ScHF7 


End  Listing  Two 
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16-BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


DEC  Professional 
300  Microcomputers 

I  have  some  important  (and  expen¬ 
sively  acquired)  information  for  those  of 
you  looking  speculatively  at  the  new  PC- 
300  series  of  personal  microcomputers 
being  sold  by  Digital  Equipment  Corp. 
Like  everyone  else  who  read  the  adver¬ 
tisements  and  saw  the  TV  commercials,  I 
was  impressed  by  the  styling  and  specifi¬ 
cations  of  the  machine,  and  found  the 
idea  of  a  PDP-1 1  compatible  computer 
on  a  desktop  running  an  operating  system 
based  on  RSX-11M  to  be  very  appealing. 
As  soon  as  the  machine  was  officially 
announced,  I  placed  my  order  for  a  PC- 
350  with  the  local  DEC  Product  Center, 
and  thereby  hangs  a  sad  tale. 

When  we  placed  an  order  in  the  sum¬ 
mer,  the  salesperson  estimated  delivery  to 
be  in  late  September.  After  two  months 
without  a  word,  we  called  them  back  and 
were  told  it  would  arrive  in  late  Novem¬ 
ber.  The  new  year  came  and  went  with¬ 
out  a  word  from  DEC,  in  spite  of  several 
letters  I  wrote  trying  to  get  some  infor¬ 
mation  about  delivery  status,  and  finally  I 
gave  up  on  the  whole  idea  of  buying  a 
PC-350  and  forgot  about  it. 

Much  to  my  surprise,  in  July  1983 
(almost  a  year  after  the  original  order  was 
placed )  a  truck  with  a  DEC  logo  rolled  up 
and  dropped  off  three  large  boxes  con¬ 
taining  the  keyboard,  monitor,  and  sys¬ 
tem  unit  for  a  PC- 350.  Unpacking  it,  1 
began  to  get  a  little  apprehensive  when 
the  chic  grey  two-inch  binder  and  box 
titled  “Professional  300  Diskette  System” 
contained  only  a  diagnostic  diskette  and  a 
50-page  manual  (consisting  mostly  of  pic¬ 
tures)  on  how  to  hook  up  the  various 
parts  of  the  machine  and  plug  it  in.  No 
sign  of  any  other  software,  and  the  pack¬ 
ing  slip  was  marked  “SHIP  AS  IS.” 

After  assembling  the  PC-350  and 
verifying  that  it  did  indeed  run  the  diag¬ 
nostics,  I  began  to  investigate  the  little 
matter  of  the  missing  operating  system. 
After  all,  the  original  salesperson  claimed 
(and  our  purchase  order  clearly  stated) 
that  a  diskette-based  operating  system  and 
development  tools  were  to  be  included. 
Suddenly  the  local  DEC  Product  Center 
disclaimed  all  knowledge  and  responsibil¬ 
ity  for  the  PC -3 00  series,  stating  that 
marketing  and  support  for  those  machines 
had  been  taken  over  by  the  main  offices 
in  Marlboro,  Massachusetts.  The  original 
salesperson,  as  is  usual  for  these  computer 
horror  stories,  was  no  longer  anywhere  to 
be  found. 


Calls  to  other  DEC  dealers  and  OEM’s 
in  the  area  finally  uncovered  the  amazing 
fact  that  (contrary  to  the  original  claims) 
no  diskette-based  operating  system  has 
been  released  at  all!  If  you  want  a  PC-350 
that  does  anything,  you  have  to  buy  the 
hard  disk  option,  to  the  tune  of  another 
$5,000.  The  PC-325  is  a  dead  issue,  since 
it  has  no  room  for  a  hard  disk  expansion. 

Even  after  you  shell  out  additional 
money  for  a  hard  disk,  you  will  not  be 
able  to  do  any  program  development  on 
the  PC-350.  DEC  apparently  has  no  plans 
to  make  even  an  assembler  and  debugger 
available  to  run  on  the  microcomputer 
itself.  Instead,  they  want  you  to  buy  a 
“Programmer’s  Toolkit”  that  runs  on  a 
PDP-11/40  or  VAX  -  the  toolkit  costs 
some  $4,000,  not  counting  the  price  of 
the  VAX,  of  course.  I  guess  the  lesson  to 
be  derived  from  this  story  is  that  DEC  is 
trying  to  make  it  impossible  for  the 
average  small  software  house  to  produce 
packages  for  the  PC-300  series,  and  I 
suspect  that  they  are  going  to  be  quite 
successful  in  this  objective.  In  the  mean¬ 
time,  I  have  a  very  stylish  grey  DEC 
paperweight,  and  I  don’t  think  I’m  going 
to  pay  for  it. 

Function  Macros  for  the  8086/88 

Ron  Burk  of  Lawrence,  Kansas, 
writes:  “After  following  the  discussion  in 
the  16-Bit  Software  Toolbox  about  stack 
arrangements  and  the  BP  register,  I  came 
to  the  conclusion  that  this  is  a  good  thing 
to  figure  out  once  and  then  forget.  Accor¬ 
dingly,  I  constructed  the  accompanying 
macros  (Listing  One,  page  100),  which 
mechanize  some  of  the  repetitiveness  of 
8088  programming.  They  are  used  to  cre¬ 
ate,  enter,  and  return  from  functions  (or 
procedures  if  you  prefer).  The  BP  register 
is  maintained  in  such  a  way  that  argu¬ 
ments  to  functions  and  local  variables  are 
located  at  fixed  offsets  from  it. 

“The  package  consists  of  five  macros 
that  are  much  easier  to  use  than  they 
were  to  make. 

“The  BENTRY  macro  defines  the 
entry  point  of  a  function.  You  supply  it 
with  the  name  of  the  function  and  the 
names  of  the  arguments  to  the  function 
(which  should  have  been  pushed  on  the 
stack  by  the  caller).  It  saves  the  current 
BP  register  on  the  stack  and  changes  it  to 
point  to  the  top  of  the  stack.  It  also  de¬ 
fines  the  names  of  the  arguments  to  the 
function  as  positive  offsets  to  the  BP,  like 
[BP+2] ,  [BP+4] ,  etc. 

“The  AUTO  macro  defines  ‘automa¬ 


tic’  storage  for  local  variables  to  the  func¬ 
tion.  These  variables  are  offsets  in  the 
stack  and  automatically  disappear  when 
the  function  returns.  The  SP  register  is 
decremented  in  order  to  allocate  the 
named  variables,  which  are  really  negative 
offsets  to  the  BP  register  (for  example 
[BP-2]  ). 

“The  SAVE  macro  saves  the  named 
registers  on  the  stack  in  a  certain  order.  It 
also  sets  flags  so  that  the  BEND  macro 
knows  what  (if  any)  registers  have  to  be 
popped. 

“The  BEND  macro  defines  the  end 
of  the  function  and  pops  off  any  saved 
registers  in  the  correct  order,  then  re¬ 
adjusts  the  stack.  It  also  defines  a  label 
(consisting  of  the  function  name  followed 
by  _end)  so  that  you  can  easily  jump  to 
the  return  code. 

“Finally,  the  BCALL  macro  pushes 
arguments  (if  any)  on  the  stack  and  then 
calls  the  named  function. 

“The  macros  include  some  rudimen¬ 
tary  error  checking  in  order  to  catch  obvi¬ 
ous  mistakes  in  using  them.  They  also 
print  function  names  at  the  beginning  and 
end  of  each  function,  which  sometimes 
makes  it  easier  to  find  mistakes.  The  fol¬ 
lowing  skeleton  shows  a  prototypical  use 
of  the  macros: 

bentry  myfunc,<argl,arg2,arg3> 
auto  <locall,local2,local3> 

save  <cx,dx,flags> 


(body  of  function) 


bend  myfunc 

“In  this  example,  the  macros  would 
cause  the  symbol  argl  to  be  equal  to 
[BP+8].  The  BEND  macro  expands  into 
code  to  restore  the  saved  registers  and  ad¬ 
just  the  stack,  then  execute  the  proper 
RET  instruction.  It  also  defines  the  label 
myfunc_end  to  be  used  as  a  target  for 
branches  to  the  exit  point  from  within 
the  function. 

“It  is  hard  to  construct  a  realistic 
example  that  is  reasonably  small,  so  I 
have  enclosed  a  dummy  example  (Listing 
Two,  page  106)  that  can  be  assembled  by 
the  readers  to  demonstrate  the  expansion 
of  each  macro.  Although  my  assembler 
doesn’t  seem  to  mind,  the  assembler 
documentation  states  that  it  is  an  error 
to  redefine  a  symbol  via  EQU.  To  avoid 
doing  this,  the  macros  employ  some 
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trickery.  If  a  local  variable  named  FRED 
is  to  be  defined,  it  is  defined  with  an 
EQU  to  be  [BP+FRED@] ,  and  FRED@ 
is  defined  (or  redefined)  to  be  the  correct 
decimal  offset  via  the  “=’  operator. 

“Even  for  people  who  dislike  one  or 
more  aspects  of  the  macros,  they  are  use¬ 
ful  in  strictly  didactic  sense,  for  they  pro¬ 
vide  examples  of  many  features  of  the 
MS-DOS  assembler’s  macro  facility.  These 
macros  are  free  to  anyone  who  is  willing 
to  type  them  in.” 


More  Low-Res  Graphics  for  IBM  PC 

Robin  Myers,  of  Livermore,  Califor¬ 
nia,  writes:  “In  the  December  1982  DDJ, 
you  presented  a  method  for  obtaining 
low-resolution,  16-color  graphics  on  the 
IBM  PC.  I  have  since  tried  the  routine  and 
found  one  very  annoying  problem:  How 
do  1  get  back  to  alphanumeric  mode? 

“Having  the  ability  to  display  16- 
color  graphics  is  nice,  but  not  very  useful 
without  a  more  general  method  of  draw¬ 
ing  in  this  mode.  So  I  have  included  a  set 
of  BASIC  subroutines  (Listing  Three, 
page  106),  which  support  changing  from 
80  x  25  alpha  text  to  160  x  100  graphics 
mode  and  back  again,  point  plotting,  and 
line  drawing.  These  routines  were  not 
optimized  for  execution  speed,  but  were 
written  to  show  the  methods  only.” 

Listing  Four  (page  111)  is  a  simple 
demonstration  program  that  draws  a  set 
of  randomly  corrected  lines  in  the  16- 
color,  low-resolution  graphics  mode. 


An  Appeal 

Our  thanks  to  Robin  Myers  and  Ron 
Burk  for  a  very  educational  set  of  contri¬ 
butions.  Readers,  please  keep  the  pro¬ 
grams  coming!  The  lapse  of  time  between 
your  donation  and  its  appearance  in  DDJ 
will  be  kept  to  a  minimum  if  you  send 
machine-readable  source  code  on  stan¬ 
dard  8-inch  CP/M  or  any  IBM  PC  514-inch 
disk  format.  Next  month:  68000  Tools. 


(Listings  begin  on  page  100) 
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16-Bit  Toolbox  (Text  begins  on  page  98) 

Listing  One 


•;  BMAC  -  Macros  for  8088  Assembly  Language 
;;  Ron  Burk,  June  1983 

t  t 


@argdef  macro  argnames 

@nargs=0 

if nb<argnames> 

irp  dummy ,  Orgnames'* 
@nargs=@nargs+2 
endm 

@ i=@nargs+2 
irp  arg , <argnames> 
arg&&@=@ i 
ifndef  arg 

arg  equ  [bp  +  arg&&@] 
endif 
@ i=@ i-2 
endm 
endif 
endm 


;;  Internal  mac  for  defining  args 
;;  @nargs  is  #  of  bytes  for  arguments 
;;  If  there  were  any  arguments 
;;  First,  count  #  of  args 
;;  2  bytes  per  argument 

;;  Allow  2  bytes  for  return  address 
;;  For  each  argument 
;;  Define  a  redefinable  offset 

;;  Define  name  itself 

;;  Next  arg  is  2  bytes  lower 


;;  End  @argdef  macro 


@err  macro  msg  ;;  Print  error  message  if  in  pass  1 

if  1 

%out  msg 
endif 

endm  ;;  End  of  @err  macro 


@check  macro  extra ,macname 
ifnb<extra> 

@err  <You  forgot  angle  brackets 
endif 
endm 


; ;  Checks  for  bad  invocation 
macname  macro> 

; ;  End  macro  @check 


bentry  macro  func , argnames, mistake  ;; 

/  i 

@nlv=0  ; ; 

@nsr=0  ;; 

@savefl=0  ;; 

irp  flag,<@ax,@bx,@cx,@dx,@si,@di,@ds,@ss 
flag  =  0  ;  ; 

endm 

if b<func> 

@err  <Missing  function  name  on  bentry 

else 


Defines  procedure 
@nlv  is  #  of  bytes  needed 
for  local  variables 
#  of  bytes  for  saved  regs 
Flag:  save  macro  has  been  used 
@es, @flags> 

Initialize  register  flags 


macro> 


@err  <!>!>!>Begin  func> 
end  i  f 

@check  mistake , bentry 
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©argdef  <argnames> 
func  proc 
push  bp 
mov  bp,sp 
endm 


Define  argument  offsets 
Define  a  procedure 
Save  previous  BP 
Make  new  BP 
End  bentry  macro 


auto  macro  vars, mistake 
if  @savefl 

©err  <***ERROR***  must  not  save  be 
endif 

©check  mistake, auto 
irp  var,<vars> 

var&&@=-  (@nlv+2) 
ifndef  var 

var  equ  [bp  +  var&&@] 
endif 

@nlv=@nlv+2 

endm 

sub  sp,@nlv 
endm 

©pop  macro  reg 
if  @&reg 

ifidn<reg>,<flags> 
popf 
else 
pop  reg 
endif 
endif 
endm 

bend  macro  func 
if b<f unc> 

©err  <Missing  name  on  bend  macro> 
endif 

©err  <!<!<!<End  func> 
f unc&_end : 

irp  reg,<flags,es,ss,ds,di,si,dx,cx, 
©pop  reg 

endm 
if  ©nlv 

add  sp,@nlv 
endif 
pop  bp 
ret  ©nargs 
func  endp 
endm 


;;  Defines  local  variables 
;;  Must  not  use  save  before  auto! 
re  auto> 


;;  Add  2  to  skip  old  BP 


; ;  bump  SP  past  local  vars 
; ;  End  auto  macro 

;;  Internal  macro  to  pop  a  register 
;;  If  we  saved  this  reg 

;;  Use  correct  inst  for  flags 

;;  Or  ordinary  pop 

; ;  End  ©pop  macro 
;;  Define  end  of  procedure 


;;  Define  an  ending  label 
,ax> 


;;  If  any  local  vars 
;;  Release  local  vars 

;  ;  Restore  old  BP 

;  ;  Return  and  pop  args 

;;  Define  end  of  procedure 


(Continued  on  next  page) 
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16-Bit  Toolbox  (Listing  continued,  text  begins  on  page  98) 

Listing  One 


@save  macro  rl,r2 
if idn<rl>,<r2> 

@&r 1=1 
@found=l 
endif 
endm 

save  macro  regs, mistake 
@savef 1=1 

@check  mistake, save 
irp  reg,<regs> 

@found=0 

irp  regname , <ax ,bx , cx ,dx , si ,di , 
@save  regname, reg 
endm 

ife  @found 

@err  <***ERROR***  'reg':  Unknown  re 
endif 


;;  Famulus  of  save  macro 
;;  If  they  are  the  same 
;;  Set  flag  variable 
;;  Tell  caller  we  found  it 

; ;  End  @save  macro 

;;  Macro  for  saving  registers 
;;  For  error  checking 


;;  Haven't  found  reg  yet 
s , ss , es , f lags> 

;;  Set  corresponding  macro  variable 

;;  If  we  don't  know  that  name 
ister  name  in  save> 


endm 

irp  reg,<ax,bx,cx,dx,si,di,ds,ss,es,flags> 

if  @&&reg  ;;  If  we're  supposed  to  save  that  one 

ifidn<flags>,<reg> 
pushf 
else 

push  reg 
endif 
endif 

endm 

en<^m  ; ;  End  save  macro 


bcall  macro  func ,args , mistake 
@check  mistake, func 
ifnb<args> 

irp  arg,<args> 
push  arg 
endm 
endif 
call  func 
endm 


;;  Macro  for  calling  procedure 

;;  If  we're  supposed  to  push  anything 

;;  Push  whatever  on  the  stack 

;;  End  of  bcall  macro 
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Listing  Two 


page 

,132 

nop 

i 

bend 

lain 

.xlist 

iiii 

include 

a.'biacs.asi 

bentry 

funl,<len> 

.list 

auto 

<a,b,c> 

t 

save 

(flags,  cx,es,bx> 

pgiseg  segient 

nop 

assute 

cs: pgiseg , ss: pgiseg , ds: pgiseg , es: pgiseg 

nop 

•ainentrys 

cld 

■ov 

bp,sp 

;  Initialize  BP 

je 

funl_end 

bentry 

■ain 

;  Define  lain  function 

nop 

auto 

<len> 

bend 

funl 

nop 

)  Body  of  function  ’tain’ 

cld 

"j  goes  here 

cld 

;  (whatever) 

pgiseg  ends 

bcall 

funl , <len> 

;  Might  call  sotething  else 

end 

■ainentry 

16-Bit  Toolbox 

Listing  Three 


;  Local  variables 

j  Save  registers  if  you  ttant 


j  Body  of  function  ’funl’ 
j  Label  of  return  of  ’funl’ 


End  Listing  Two 


50000 

50010 

50020 

50030 

50040 

50050 

50060 

50070 

50080 

50090 

50100 

50110 

50120 

50130 

50140 

50150 

50160 

50170 

50180 

50190 

50200 

50210 

50220 

50230 

50240 

50250 

50260 

50270 

50280 

50290 

50300 

50310 


REM  entry  point  for  point  plotting 
GOTO  50120 

REM  entry  point  for  line  drawing 
GOTO  50410 

REM  entry  point  to  set  up  low  res  graphics  display 
GOTO  50970 

REM  entry  point  to  restore  normal  80  x  25  alpha  display 
GOTO  51160 

REM  entry  point  to  define  misc  functions 
GOTO  51260 

•  ******************************* 

I 

'  DRAW  A  POINT 

■ 

'  on  entry  set  ZX,ZY  to  x,y  coordinates  for  the  point 

'  DOTCOLOR  to  point  color 

• 

1  get  the  value  currently  at  the  byte  location 
'  for  the  dot 

DOTNOW  =  PEEK  (  FNOFFSET% (  ZX,ZY  )  ) 

f 

'  if  the  new  dot  is  to  go  into  the  left  half  of 
'  the  byte,  then  mask  off  the  upper  nybble  (preserving 
'  the  lower  nybble)  then  OR  in  the  new  dot 

I 

IF  FNMOD2% (  ZX  )  <>  0  GOTO  50330 

DOTCLR  =  (DOTNOW  AND  &HF)  OR  (DOTCOLOR  *  16) 

GOTO  50370 

i 

'  if  the  new  dot  is  to  go  into  the  right  half  of  the 
'  byte,  then  mask  off  the  lower  nybble  (preserving  the 


'  upper  nybble)  and  OR  in  the  new  dot 


(Continued  on  next  page ) 
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16-Bit  Toolbox  (Listing  continued,  text  begins  on  page  98) 

Listing  Three 


50320 

50330 

50340 

50350 

50360 

50370 

50380 

50390 

50400 

50410 

50420 

50430 

50440 

50450 

50460 

50470 

50480 

50490 

50500 

50510 

50520 

50530 

50540 

50550 

50560 

50570 

50580 

50590 

50600 

50610 

50620 

50630 

50640 

50650 

50660 

50670 

50680 

50690 

50700 

50710 

50720 

50730 

50740 

50750 

50760 

50770 

50780 

50790 

50800 


DOTCLR  =  (DOTNOW  AND  &HF0)  OR  DOTCOLOR 

I 

'  display  the  dot  (write  it  back  to  refresh  buffer) 

i 

POKE  FNOFFSET%  (  ZX,ZY  ), DOTCLR 
RETURN 


'  DRAW  A  LINE 

i 

1  on  entry  set:  XI, Y1  to  x,y  coordinates  for  starting  point 

1  X2,Y2  to  x,y  coordinates  for  ending  point 

'  DOTCOLOR  to  color  for  entire  line 

I 

'  compute  the  change  in  x  and  y 

I 

DELTAX  =  X2  -  XI  :  DELTAY  =  Y2  -  Y1 
'  Draw  a  point 

I 

IF  DELTAX  <>  0  OR  DELTAY  <>  0  GOTO  50620 

1  Just  draw  a  point  if  the  line  has  zero  length 

■ 

ZX  =  XI  :  ZY  =  Y1  :  GOSUB  50000 
RETURN 

I 

'  Check  for  case  of  horizontal  line 

I 

IF  DELTAY  <>  0  GOTO  50710 
ZY  =  Y 1 

FOR  ZX  =  XI  TO  X2  STEP  SGN (  DELTAX  ) 

GOSUB  50000 
NEXT  ZX 
RETURN 

i 

'  Check  for  case  of  vertical  line 

I 

IF  DELTAX  <>  0  GOTO  50800 
ZX  =  XI 

FOR  ZY  =  Y1  TO  Y2  STEP  SGN (  DELTAY  ) 

GOSUB  50000 
NEXT  ZY 
RETURN 

I 

'  Case  for  slope  >  1 

I 

IF  ABS (  DELTAY  )  <  ABS  (  DELTAX  )  GOTO  50900 
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50810 

50820 

50830 

50840 

50850 

50860 

50870 

50880 

50890 

50900 

50910 

50920 

50925 

50930 

50940 

50950 

50960 

50970 

50980 

51000 

51010 

51020 

51030 

51040 

51050 

51060 

51070 

51080 

51090 

51100 

51110 

51120 

51130 

51140 

51150 

51160 

51170 

51180 

51190 

51200 

51210 

51220 

51230 

51240 

51250 

51260 

51270 

51280 


SLOPE  =  DELTAX  /  DELTAY 
FOR  ZY  =  Y1  TO  Y 2  STEP  SGN (  DELTAY  ) 
ZX  =  SLOPE  *  (  ZY  -  Y1  )  +  XI 
GOSUB  50000 
NEXT  ZY 
RETURN 

I 

'  Case  for  slope  <=1 

I 

SLOPE  =  DELTAY  /  DELTAX 
FOR  ZX  =  XI  TO  X2  STEP  SGN  (DELTAX  ) 
ZY  =  SLOPE  *  (  ZX  -  XI  )  +  Y1 
GOSUB  50000 
NEXT  ZX 
RETURN 


'  Set  up  low  resolution  160  x  100 

I 

SCREEN  0  :  WIDTH  80 
KEY  OFF  :  CLS 
OUT  &H3D8 , 9 
A%  =  &H3D4  :  D%=&H3D5 
OUT  A% , 4  :  OUT  D%,&H7F 
OUT  A% , 6  :  OUT  D%,&H64 

OUT  A%,7  :  OUT  D%,&H70 
OUT  A% , 9  :  OUT  D%,1 
DEF  SEG  =  &HB800 
FOR  CC%  =  0  TO  &H3FFE  STEP  2 
POKE  CC% , &HDE  :  NEXT 
FOR  AT%  =  1  TO  S.H3FFF  STEP  2 
POKE  AT% , 0  :  NEXT 
RETURN 

i 
i 

'  reset  160  x  100  graphics  mode 

I 


16-color  mode 

'  set  up  80  x  25  alpha 
'  clear  screen 
'  disable  blink  attribute 
'  crt  controller  ports 
'  vertical  total 
'  vertical  displayed 
1  vertical  sync  position 
'  max  scan  line  address 
'  display  buffer  segment 
'  all  character  codes  preset 
'  to  special  character 
'  all  attributes  preset 
'  to  black 


to  80  x  25  alpha  mode 


OUT  A% , 4 
OUT  A% , 6 
OUT  A% , 7 
OUT  A% , 9 
CLS 
RETURN 


OUT  D% , & H1F 
OUT  D% , &H19 
OUT  D% , &H1C 
OUT  D% , 7 


'  vertical 
'  vertical 
'  vertical 
'  max  scan 


total 
displayed 
sync  position 
line  address 


1  define  miscellaneous  functions  for  160  x  100  graphics 

I 

1  compute  byte  offset  into  display  buffer  based  on  X,Y 


(Continued  on  next  page ) 
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16-Bit  Toolbox  (Listing  continued,  text  begins  on  page  98) 

Listing  Three 


51290  DEF  FNOFFSET%  (  X%,Y%  ) 

51300  ' 

51310  '  modulo  2  function 
51320  DEF  FNM0D2%(  X%  )  =  X% 

51330  RETURN 

16-Bit  Toolbox 

Listing  Four 

100  1  Sample  program  to  produce  set  of  randomly  colored 
110  '  lines,  using  160  X  100  low  resolution  16-color 
120  '  graphics  mode 
130  ' 

140  GOSUB  50080  '  define  misc  functions 

150  GOSUB  50040  '  set  up  160  X  100  display 

160  XI  =  0  :  Y1  =  0  :  X2  =  159 
170  FOR  Y2  =  0  TO  99  STEP  2 

175  DOTCOLOR  =  INT(RND*15)  :  IF  DOTCOLOR=0  OR  D0TC0L0R=8  GOTO  185 
180  GOSUB  50020 
185  NEXT  Y2 

190  FOR  X2  =  158  TO  0  STEP  -2 

195  DOTCOLOR  =  INT(RND*15)  :  IF  DOTCOLOR=0  OR  D0TC0L0R=8  GOTO  205 
200  GOSUB  50020 
205  NEXT  X2 

240  IF  INKEY$  =  " "  GOTO  240  '  wait  for  any  key 

250  GOSUB  50060  '  restore  normal  alpha  mode 

260  STOP 

End  Listing  Four 


=  160  *  Y%  +  (  X%  OR  1  ) 

-  (  INT (  X%  /  2  )  *  2  ) 

End  Listing  Three 


Dr.  Dobb’s  Journal,  Number  84,  October  1983 


111 


CP/M  EXCHANGE 


by  Robert  Blum 


When  I  talk  about  a  program  in  this 
column  that  I  am  impressed  with  I  usually 
try  to  summarize  its  features  by  including 
a  chart  of  functions  or  at  least  a  command 
summary.  I  adopted  this  method  of  re¬ 
view  after  years  of  requesting  information 
on  products  and  receiving  sales  brochures 
that  gloss  over  any  merits  that  the  product 
may  have.  This  type  of  brochure  is  fine 
for  the  uninitiated  computer  user,  but 
does  very  little  for  me.  What  I  want  to  see 
is  a  brief  synopsis  of  what  the  product  will 
do  and  how  it  might  fit  into  my  operating 
environment.  Unfortunately,  getting  this 
type  of  information  usually  requires  pur¬ 
chasing  a  demo  system  whose  price  may 
or  may  not  be  refundable  if  the  complete 
system  is  bought  later.  The  alternative  to 
the  demo  system  is  to  call  the  manufac¬ 
turer  and  talk  with  a  technical  support 
representative  —  that  is,  if  you  can  get 
through  the  switchboard  without  a  serial 
number. 

Well,  that’s  the  state-of-the-art!  I 
do  hope  that  the  charts  and  such  that 
I  present  here  are  helpful. 


Hidden  Treasures 

A  complete  set  of  utility  subroutines 
is  absolutely  necessary  when  writing  any¬ 
thing  more  complex  than  a  very  simple 
assembler  program  —  that  is,  unless  you 
enjoy  recoding  all  the  fairly  small,  but 
necessary,  CP/M  interface  and  format 
conversion  routines  for  each  new  program. 
Two  solutions  exist  for  this  problem,  and 
both  are  available  for  next  to  nothing  in 
the  public  domain. 

Several  macro  libraries  have  been  in 
the  public  domain  for  quite  some  time 
that  offer  most  of  what  you  need.  To  use 
them  requires  a  macro  assembler  such  as 
MAC  or  M80.  When  using  them,  expect 
compile  times  to  be  longer  than  you  are 
accustomed  to,  especially  when  defining 
several  sequential  files  in  the  same  pro¬ 
gram  with  the  FILE  macro.  I  have  experi¬ 
enced  delays  of  several  minutes  while  the 
macros  are  being  expanded.  During  this 
time,  no  file  activity  is  taking  place  so 
you  will  have  no  indication  as  to  whether 
the  assembler  has  gone  south  or  not.  Be 
patient,  it  will  finish  in  due  time.  When 
producing  hard  copy  of  the  program,  be 
prepared  for  a  much  larger  listing  than 
you  may  have  expected.  Now  would  be  a 
good  time  to  brush  up  on  your  assembler’s 
switches  or  flag  settings  to  suppress  the 
statements  generated  through  macro  ex¬ 
pansion.  Setting  one  of  these  will  trim 


down  your  listing  to  a  more  reasonable 
size.  One  drawback  to  using  macros  is 
that  they  may  generate  labels  that  can 
duplicate  others  that  you  have  written. 
After  a  few  uses,  you  will  begin  to  re¬ 
member  what  the  generated  labels  are  and 
avoid  using  them. 

Rather  than  using  macros,  I  prefer 
pre-assembled  subroutines,  which  can  be 
linked  together  with  my  program.  Ron 
Conn  has  submitted  to  the  SIG/M  library 
the  most  complete  set  of  subroutines  that 
I  have  found.  They  are  available  on  SIG/M 
volumes  88,  89,  and  90,  both  in  relocatable 
form  (.REL  files)  and  in  source  code  form 
(.MAC  files).  Included  with  each  routine 
is  a  documentation  file  that  briefly,  but 
completely,  describes  each  routine’s  pur¬ 
pose  and  how  to  effectively  use  it.  To  use 
the  relocatable  version  of  them,  you  will 
need  a  linkage  editor,  such  as  LINK  or 
L80,  capable  of  accepting  standard  Micro¬ 
soft  relocatable  files.  This  also  means  that 
you  will  have  to  compile  your  program 
with  an  assembler  that  produces  this  same 
type  of  object  file. 

If  you  decide  not  to  use  the  relocat¬ 
able  version  of  SYSLIB,  you  can  include 
the  source  code  into  your  program.  Again, 
when  using  this  method,  you  run  the  risk 
of  duplicating  labels,  and  the  assembly 
time  will  balloon.  Whichever  you  choose, 
you  can’t  go  wrong  with  SYSLIB.  For  an 
abbreviated  description  of  an  older  ver¬ 
sion  of  SYSLIB’s  contents,  consult  Table 
1  (page  114). 


TUTORI/O 

Learning  all  the  ins  and  outs  of  how 
CP/M  works  from  the  Digital  Research 
documentation  can  be  a  painful  experi¬ 
ence.  Many  fine  books  have  been  written 
to  help  fill  in  the  gaps,  but  nothing  can 
rival  actually  watching  the  CPU’s  reaction 
to  each  instruction.  I  briefly  talked  about 
this  subject  several  months  ago  and  obvi¬ 
ously  feel  just  as  strongly  about  it  today. 

Roy  Lipscomb  of  Logic  Associates 
wrote  to  me  in  response  to  that  column. 
He  pointed  out  that  he  had  recently  com¬ 
pleted  TUTORI/O  —  a  program  that  would 
supposedly  ease  the  task  of  learning  how 
CP/M  performs  disk  I/O  operations.  The 
documentation  that  he  enclosed  was  in¬ 
triguing.  It  explained  that  all  the  differ¬ 
ent  disk-related  BDOS  functions  could  be 
exercised  through  single-letter  commands, 
and  the  resulting  status  codes  and  save 
areas  are  automatically  displayed  for  visual 
inspection.  I  was  caught  by  my  thoughts 


on  how  many  hours  I  had  spent  pawing 
through  piles  of  source  code  and  sitting 
frustrated  in  front  of  a  CRT  attempting 
to  relate  CP/ M’s  documentation  to  my 
program’s  operation.  I  wanted  to  see  if 
TUTORI/O  could  live  up  to  its  billing; 
so  I  requested  a  copy  for  review. 

Preparing  TUTORI/O  for  use  is  sim¬ 
ple.  It  is  a  single  phase  program;  so  only 
one  program  file  and  the  documentation 
file  had  to  be  copied  onto  my  backup  dis¬ 
kette.  I  found  out  later  that  it  requires 
the  use  of  a  debug  program  such  as  DDT, 
SID,  or  whatever.  So,  while  creating  your 
backup  diskette,  also  copy  whatever  de¬ 
bugger  you  use  as  well.  I  first  printed  the 
documentation  and  gave  it  the  once  over. 
It  is  brief  but  complete,  although  it  does 
assume  that  you  have  some  prior  knowl¬ 
edge  of  CP/ M’s  BDOS  functions.  I  found 
one  area  to  be  confusing  at  first ;  but  after 
some  further  study,  it  became  clear. 

Executing  TUTORI/O  is  as  simple  as 
typing  its  name  followed  by  two  optional 
parameters.  The  first  is  the  name  of  your 
debug  program  followed  by  the  line  length 
of  your  CRT.  If  either  parameter  is 
omitted,  a  suitable  default  is  automatical¬ 
ly  selected.  The  debug  program  is  used  to 
allow  you  to  look  into  and  change  areas 
of  memory  other  than  those  addressed  by 
TUTORI/O. 

Taking  TUTORI/O  to  task,  I  loaded 
it  specifying  that  I  wanted  to  use  SID  as 
my  debug  program  and  that  my  CRT  has 
an  80-column  display.  I  was  greeted  with  a 
menu  of  commands  and  a  terse  descrip¬ 
tion  of  each.  I  first  created  a  test  file  with 
the  (M)ake  command  and  was  automa¬ 
tically  presented  with  the  return  status 
and  a  hexadecimal  display  of  the  default 
FCB  at  5CH  and  the  default  DMA  area  at 
80H.  Next,  I  sequentially  wrote  several 
sectors  into  the  file.  As  each  sector  was 
written,  I  was  informed  of  the  BDOS 
return  code  and  an  updated  display  of  the 
FCB.  To  put  TUTORI/O  to  the  acid  test, 
I  exited  to  my  debug  program,  a  single¬ 
letter  command,  and  changed  the  random 
record  number  to  a  value  well  beyond 
what  the  first  extent  could  handle.  Return¬ 
ing  back  to  TUTORI/O,  again  a  single¬ 
letter  command,  I  requested  that  the  next 
record  be  randomly  written  into  the  file. 
A  little  more  disk  activity  occurred  this 
time  while  the  first  extent  was  written 
back  to  disk  and  a  new  one  created.  The 
resultant  display  was  breathtaking.  The 
record  number  that  I  chose  had  not  only 
exceeded  the  first  extent’s  capacity,  but 
the  second  one  as  well.  What  I  saw  dis- 
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Table  I 

A  Very  Abbreviated  List  of  SYSLIB  Routines 


Directory  Manipulation  Routines 

DIRECT  -  loads  a  copy  of  the  directory  of  the  currently  logged-in 
disk  drive  into  the  32-  x  64 -byte  buffer  pointed  to  by  HL  se¬ 
lects  all  file  entries  which  match  the  contents  of  the  1 1  -byte  file 
name  buffer  pointed  to  by  DE  (buffer  may  contain  ?'s  as  wild 
specifications),  and  alphabetizes  the  entries  in  the  buffer  either 
by  file  name/type  or  by  file  type/name.  Only  entries  where  the 
extent  is  zero  (1st  file  entry)  are  returned. 

DIR  —  loads  a  copy  of  the  directory  of  the  currently  logged-in 
disk  drive  into  the  32-  x  64-byte  buffer  pointed  to  by  HL.  On  re¬ 
turn,  A  contains  a  count  of  the  number  of  entries  in  the  directory. 

Numeric  Evaluation  Routines 

EVAL  —  converts  the  character  string  pointed' to  by  HL  into  the 
16 -bit  binary  number  represented  by  it.  EVAL  performs  the 
conversion  until  a  non-hexadecimal  character  is  encountered,  at 
which  time  it  looks  at  the  last  character  and  the  previous  charac¬ 
ter  to  determine  if  the  string  is  representing  a  binary,  octal,  deci¬ 
mal,  or  hexadecimal  number.  Input  string  characters  may  be 
upper  or  lower  case.  Valid  formats  for  the  input  string  are 
bbbbbbbbbbbbbbbbB  —  b=0  or  b=  1 ;  Binary  string 
ttttt  or  tttttD  —  0  <=  t  <=  9;  Decimal  string 
hhhhH  or  hhhhX  —  0  <=  h  <=  F;  Hexadecimal  string 
oooooooO  or  oooooooQ  —  0  <=  o  <=  7;  Octal  string 

Byte-Oriented  File  Input/Output 

FO$OPEN,  F10$OPEN,  F20$OPEM,  F30$OPEN  -  open  the  file 
whose  FCB  is  pointed  to  by  DE  for  output  (use  with  F$PUT). 

FO$CLOSE,  F10$C LOSE,  F20$CLOSE,  F30$CLOSE  -  closethe 
file  previously  opened  by  the  corresponding  FO$OPEN  routine. 
Use  of  these  routines  is  mandatory  after  output  to  the  file  (using 
the  corresponding  F$PUT  routine)  is  complete. 

F$GET,  F1$GET,  F2$GET,  F3$GET  -  get  the  next  byte  in  se¬ 
quence  from  the  file  previously  opened  by  the  corresponding 
F ISOPEN  routine.  The  byte  is  returned  in  Register  A. 

F$PUT,  F1$PUT,  F2$PUT,  F3$PUT  -  put  the  byte  in  Register 
A  onto  the  end  of  the  file  previously  opened  by  the  correspond¬ 
ing  FO$OPEN  routine. 

CP/M  File  Input/Output  Routines 

F$OPEN  —  opens  the  file  specified  by  the  FCB  pointed  to  by  DE. 
If  a  file  is  not  found,  F$OPEN  asks  the  user  (on  CON:)  if  he  or 
she  wishes  to  create  it  and  does  so  if  the  answer  is  'Y'  or  'y' 
(F$OPEN  simply  returns  with  an  appropriate  error  code  if 
the  answer  is  negative). 

F$CLOSE  —  closes  the  file  whose  FCB  is  pointed  to  by  DE. 

F$MAKE  —  creates  (Makes)  the  file  whose  FCB  is  pointed  to  by  DE. 

FSDELETE  —  deletes  the  file  whose  FCB  is  pointed  to  by  DE.  If  a 
file  does  not  exist,  nothing  happens  (no  error  message  or  code  is 
given). 

F$READ  —  reads  next  block  (128bytes)  from  theopened  file  whose 
FCB  is  pointed  to  by  DE  into  TBUFF  (buffer  at  80H-0FFH). 

FSWRITE  —  writes  next  block  (128  bytes)  from  TBUFF  (buffer  at 
80H-0FFH)  to  the  opened  file  whose  FCB  is  pointed  to  by  DE. 

Input  Line  Editor 

INLINE  —  allows  the  user  to  input  a  line  of  text  from  CON:  into 
the  buffer  pointed  to  by  H  L.  The  user  is  allowed  to  edit  the  text 
as  he  or  she  types  it. 

String  Output  Routines 

PRINT,  LPRINT  —  print  string  pointed  to  by  the  return  address 
on  CON:  (PRINT)  or  LST :  (LPRINT).  The  string  is  terminated 
by  a  binary  0.  Control  is  returned  to  byte  following  string. 

PSTR,  LPSTR  —  print  string  pointed  to  by  HL  on  CON:  (PSTR) 
or  LST :  (LPSTR).  The  string  is  terminated  by  a  binary  0. 

Numeric  Output  Routines 

PHL4HC,  LHL4HC  —  print  HL  as  four  (4)  hexadecimal  characters 
on  CON:  (PHL4HC)  or  LST:  (LHL4HCI. 

MHL4HC  —  stores  HL  as  four  (4)  hexadecimal  characters  in  the  4- 
byte  memory  buffer  pointed  to  by  DE.  On  return,  DE  points  tc 
the  byte  following  this  buffer. 


PHL5DC,  LHL5DC  -  print  HL  as  five  (5)  decimal  characters  on 
CON:  (PHL5DC)  or  LST:  (LHL5DC). 

MHL5DC  —  stores  HL  at  five  (5)  decimal  characters  in  memory  in 
the  5-byte  buffer  pointed  to  by  DE.  On  return,  DE  points  to  the 
byte  after  this  buffer. 

PHLDC,  LHLDC  —  print  HL  as  up  to  five  (5)  decimal  characters 
with  leading  spaces  «SP»  on  CON:  (PHLDC)  or  LST:  (LHLDC). 

MHLDC  —  stores  HL  as  up  to  five  (5)  decimal  characters  with  lead¬ 
ing  spaces  in  the  5-byte  memory  buffer  pointed  to  by  DE. 

PA2HC,  LA2HC  —  print  A  as  two  (2)  hexadecimal  characters  on 
CON:  (PA2HC)  or  LST:  (LA2HC). 

MA2HC  —  stores  A  as  two  (2)  hexadecimal  characters  in  the  2-byte 
memory  buffer  pointed  to  by  HL.  On  return,  HL  points  to  the 
byte  after  this  buffer. 

PA3DC,  LA3DC  —  print  A  as  three  (3)  decimal  characters  on  CON: 
(PA3DC)  or  LST:  (LA3DC). 

MA3DC  —  stores  A  as  three  (3)  decimal  characters  in  the  3-byte 
memory  buffer  pointed  to  by  HL.  On  return,  HL  points  to  the 
byte  after  the  buffer. 

PADC,  LADC  —  print  A  as  up  to  three  (3)  decimal  characters  with 
leading  spaces  «SP»  on  CON:  (PADC)  or  LST:  (LADC). 

MADC  —  stores  A  as  up  to  three  (3)  decimal  characters  with  lead¬ 
ing  spaces  in  the  3-byte  memory  buffer  pointed  to  by  HL.  On 
return,  HL  points  to  the  byte  after  this  buffer. 

String  Comparison  Routines 

SCANNER  —  scans  the  vector  of  bytes  pointed  to  by  HL  for  the 
vector  of  bytes  pointed  to  by  DE.  The  HL-byte  vector  is  B  bytes 
long  and  the  DE-byte  vector  is  C  bytes  long.  On  return,  if  found, 
HL  points  to  the  beginning  location  within  the  original  HLvector 
of  the  located  vector  and  the  zero  flag  is  set;  if  it  is  not  found, 
the  zero  flag  is  not  set  and  HL  is  not  affected  (it. points  to  the 
beginning  of  the  original  HL-byte  vector). 

General  Input  Routines 

CONDIN  —  inputs  a  character  from  CON:  if  one  is  available;  other¬ 
wise,  returns  a  flag  stating  that  a  character  is  not  available  on 
CON;. 

CST  —  inputs  the  status  of  CON:  in  Register  A.  If  read  data  are 
available,  A  =  0;  otherwise,  A  =  1 . 

CIN,  RIN  —  input  character  from  CON:  (CIN)  or  RDR:  (RIN)  in 
Register  A. 

General  Output  Routines 

COUT,  LOUT,  POUT  —  output  character  in  Register  A  to  CON: 
(COUT),  LST:  (LOUT),  or  PUN:  (POUT). 

CRLF,  LCRF  -  print  <CR>  and  <LF>  on  CON:  (CRLF)  or 
LST:  (LCRLF). 

Miscellaneous  Routines 

BDOS  —  calls  CP/M  entry  point  at  location  5  and  preserves  Regis¬ 
ters  HL  and  DE. 

CAPS  —  capitalizes  an  ASCII  character  in  Register  A  if  it  is  a  lower 
case  alphabetic  character  (a-z);  otherwise,  returns  A  unaffected. 

CIO  (CP/M  I/O  through  BIOS  JumpTable)  —  indexes  into  the  CP/M 
BIOS  jump  table  and  allows  the  user  to  address  any  routine  in 
the  BIOS  (accessible  routines  only).  It  is  called  with  Register  A 
containing  the  index  offset  and  Registers  BC  containing  any  re¬ 
quired  input  arguments. 

EN  —  exchanges  nibbles  in  Register  A;  high -order  four  bits  are 
exchanged  with  low-order  four  bits  of  Register  A. 

FILLB,  FILLBC  —  fill  an  area  of  memory  with  a  constant  byte 
value.  FILLB  can  fill  up  to  a  256-byte  buffer,  and  FILLBC  can 
fill  up  to  a  65,536-byte  (within  reason)  buffer. 

MOVEB,  MOVEBC  —  move  the  block  of  memory  pointed  to  by 
HL  to  the  memory  location  pointed  to  by  DE.  MOVEB  can 
move  up  to  a  256-byte  buffer,  and  MOVEBC  can  move  up  to  a 
65,536-byte  buffer. 

CATH  —  converts  the  ASCII  hexadecimal  character  in  the  A  Regis¬ 
ter  to  binary  in  the  A  Register. 
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played  was  the  third  extent,  and  the 
block  allocation  number  was  sitting  in  the 
second  position  of  the  FCB.  I  hate  to 
think  about  how  long  I  spent  learning 
how  CP/M  handled  random  record  opera¬ 
tions  when  version  2.2  first  came  out. 
Unfortunately,  at  that  time  I  didn’t  have 
TUTORI/O  and  had  to  use  some  very 
crude  methods  to  learn  what  I  experienced 
in  just  several  minutes  with  this  program. 
TUTORI/O  is  a  fine  product  aimed  at  the 
person  who  wants  to  learn  more  about 
the  BDOS  disk  functions  with  a  minimal 
amount  of  effort.  To  get  further  informa¬ 
tion  or  to  place  an  order  ($25.00  plus 
$6.00  handling),  contact  Roy  Lipscomb, 
Logic  Associates,  1433  W.  Thome,  Chica¬ 
go,  Illinois  60660. 


Auto  Disk  Format  Selection 

Most  of  today’s  small  computer  sys¬ 
tems  accept  at  least  two  disk  formats, 
single-  and  double-density.  A  few  others 
allow  as  many  as  six.  For  example,  the 
Tarbell  double -density  disk  controller 
can  successfully  utilize  8 -inch  disks  for¬ 
matted  in  the  standard  single -density  for¬ 
mat  of  26  128 -byte  sectors,  and,  in 
their  own  double-density  format,  of 
either  51  128-byte  sectors  or  16  512-byte 
sectors.  The  reason  for  using  these  non¬ 
standard  formats  is  to  maximize  data 
capacity  while  minimizing  memory  usage 
for  data  buffer  space.  In  the  case  of  the 
16  512-byte  sector  format,  each  track  car¬ 
ries  the  same  amount  of  data  as  the  stan¬ 
dard  8  1024-byte  sector  format  while 
saving  512  bytes  of  memory. 

To  enable  the  application  program  to 


matic  selection  method  that  I  have  seen 
used  is  what  I  call  the  “brute  force  meth¬ 
od.”  This  method  simply  begins  by  read¬ 
ing  the  disk  in  single -density.  If  a  read 
error  occurs,  the  BIOS  logic  shifts  to 
double -density  and  performs  the  read 
operation  over  agian.  This  tends  to  be  a 
bit  slow  when  logging  in  a  double-density 
disk  because  a  read  error  will  always 
occur  on  the  first  read.  This  usually  takes 
an  additional  5  to  10  seconds  depending 
on  how  laborious  the  error  recovery  rou¬ 
tines  are  over  normal  log-in  times. 

The  last,  and  most  unsophisticated, 
method  that  I  have  seen  requires  that  the 
operator  identify  the  disk  format  and 
indicate  to  the  system  what  it  is  through 
an  operator  command.  For  example,  I 
recently  had  the  opportunity  to  work  on 
an  Altos  ACS8000,  which  uses  this 
method  of  disk  format  selection.  On  this 
system  you  must  use  the  MODE  transient 
program  to  indicate  to  the  system  what 
drive  is  being  changed  and  the  disk  for¬ 
mat  being  mounted.  Even  so,  this  proce¬ 
dure  should  be  used  only  when  mounting 
a  disk  that  is  formatted  differently  than 
the  one  currently  logged  in  to  a  particular 
drive. 

Now  that  we  have  looked  at  the 
operational  aspects  of  handling  different 
disk  formats,  let’s  explore  the  BIOS  logic 
necessary  to  interface  between  CP/M,  the 
hardware,  and  the  application  program. 
The  ability  of  a  system  to  handle  different 
disk  formats  comes  from  each  attached 
physical  drive  being  assigned  a  disk 
parameter  header  (DPH),  sector  transla¬ 
tion  table  (STT),  and  a  disk  parameter 


block  (DPB).  It  is  through  these  tables 
that  CP/  M’s  BDOS  can  gain  knowledge  of 
how  large  the  data  space  is,  how  many 
directory  entries  have  been  assigned,  and 
other  information  necessary  for  it  to  suc¬ 
cessfully  perform  its  job.  The  one  key  ele¬ 
ment  that  ties  all  the  parts  together  is  the 
disk  parameter  header.  In  it  are  contained 
pointers  to  all  the  static  tables  and  work 
areas  that  are  used  when  accessing  a  drive. 
Each  drive  attached  to  the  system  must 
have  a  DPH  assigned  to  its  exclusive  use. 

When  logging  in  a  disk  through  auto¬ 
matic  selection,  the  first  task  of  the  BIOS 
is  to  determine  what  type  of  disk  has 
been  inserted  by  one  of  the  two  methods 
previously  discussed.  It  is  then  necessary 
to  update  the  DPH  for  this  drive  with 
pointers  to  the  proper  DPB  and  STT. 
Once  this  is  complete,  other  indicators 
are  also  set  to  identify  what  the  physical 
sector  size  is  and  what  the  hardware 
characteristics  are.  Since  the  DPB  and 
STT  are  not  modified  during  normal 
processing,  only  one  for  each  different 
disk  format  is  necessary.  When  two  or 
more  drives  contain  the  same  type  of  disk, 
their  DPH  will  point  to  the  same  DPB  and 
STT.  In  the  auto-select  BIOS  of  our 
example,  a  different  DPB  and  STT  for 
each  disk  type  must  be  memory-resident 
at  all  times.  This  does  impose  some  addi¬ 
tional  memory  overhead  because  each 
DPB  requires  15  bytes  and  each  STT  can 
be  as  large  as  64  bytes. 

When  not  using  an  auto-select  scheme, 
the  transient  program  called  when  mount¬ 
ing  a  new  disk  usually  contains  the  tables 


access  data  from  any  one  of  the  various 
formats  requires  that  the  BIOS  be  smart 
enough  either  to  independently  deter¬ 
mine  how  a  disk  is  formatted  or  to  be 
instructed  by  the  operator  at  the  time  a 
disk  is  mounted. 

The  Tarbell  double-density  disk  con¬ 
troller  uses  the  most  straightforward  ap¬ 
proach  to  providing  completely  automa¬ 
tic  disk  type  sensing.  The  disk  initializa¬ 
tion  utility  always  formats  the  first  track 
in  single-density  and  then  the  remaining 
tracks  in  double-density.  A  single  byte, 
contained  in  the  bootstrap  record  placed 
on  the  disk  at  SYSGEN  time,  is  then  used 
to  indicate  format  type.  When  a  warm 
start  occurs,  the  first  sector  of  track  zero, 
bootstrap  record,  is  read  to  determine 
what  the  disk  format  is  on  all  tracks  other 
than  zero.  The  CCP  and  BDOS  are  read 
from  the  second  through  26th  sectors  of 
the  first  track  in  single -density  and  the 
remainder  from  track  one  in  whatever 
format  was  indicated  in  the  bootstrap 
record.  In  the  case  of  logging  in  any  drive 
other  than  A:,  the  disk  selection  routine 
again  reads  the  bootstrap  record  to  deter¬ 
mine  disk  format  and  sets  the  appropriate 
indicators  for  subsequent  use  by  the  BIOS 
disk  handling  routines.  One  other  auto- 


Table  II 

Character  Devices 

Label 

Description 

Contents 

PDEVNM 

Physical  device  name 

Six  characters  describing  the  physical 

MODE 

Mode  of  operation 

1  —  device  may  do  input 

2  —  device  may  do  output 

3  —  device  may  do  both  input  and 

output 

4  —  baud  rates  are  software  selectable 

8  —  device  may  use  protocol 

16  —  XON/XOFF  protocol  enabled 

BAUD 

Baud  rate 

0  —  none 

1  —  50  baud 

2  —  75  baud 

3  —  110  baud 

4  —  134.5  baud 
5—150  baud 

6  —  300  baud 

7  —  600  baud 

8  —  1200  baud 

9  —  1800  baud 

10  —  2400  baud 

1 1  —  3600  baud 
12-4800  baud 

13  —  7200  baud 

14  —  9600  baud 

15  -  19.2K  baud 
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for  each  different  disk  type.  Gaining 
access  to  the  DPH  —  so  that  it  can  be 
changed  to  point  to  the  appropriate 
tables  -  is  accomplished  by  calling  the 
BIOS  entry  point  SELDSK.  When  a  re¬ 
turn  to  the  transient  program  is  made,  the 
HL  register  pair  will  contain  the  address 
of  the  DPH  for  the  selected  drive.  The 
transient  program  then  moves  the  corre¬ 
sponding  tables  into  the  BIOS  and  updates 
any  other  work  areas.  This  method  does 
save  a  little  memory,  but  requires  opera¬ 
tor  intervention  —  not  only  to  insert  the 
new  disk  into  the  drive,  but  to  log  it  in  as 
well. 

If  you  have  the  need  to  access  the 
DPB  from  an  application  program,  BDOS 
function  31  should  be  used.  The  DPB 
address  of  the  current  default  drive  is  re¬ 
turned  from  this  function  call  in  the  HL 
register  pair.  One  other  function  call  that 
may  be  of  interest  if  you  need  system 
information  on  this  level  is  BDOS  func¬ 
tion  27.  The  address  of  the  allocation  table 
for  the  current  default  drive  is  returned 
from  this  call  in  the  HL  register  pair. 

Additional  information  on  the  exact 
content  of  the  tables  that  we  have  talked 
about  can  be  found  in  the  March  and 
April  issues  of  DDJ  in  this  column. 


CP/M  Plus  Device  Tables 

One  design  concept  used  when  imple¬ 
menting  CP/M  Plus  that  was  immediately 
useful  to  me  is  the  extensive  use  of  tables 
to  describe  the  I/O  system  —  in  particular, 
the  character  device  table  that  replaces 
the  I/O  byte  of  prior  releases.  Through 
this  table,  the  characteristics  of  a  large 
number  of  character-oriented  devices  can 
be  initially  described  and  later  changed 
by  a  utility  program  to  meet  changing 
needs.  This  simplifies  the  controlling  logic 
for  each  device  because  there  is  now  a 
common  format  that  can  be  used  to 
determine  exactly  what  driver  software 
should  be  used. 

In  addition  to  simplified  driver  logic, 
it  is  now  possible  to  easily  assign  one  logi¬ 
cal  device  to  several  physical  devices  by 
using  a  utility  program.  For  example,  the 
system  console  device  could  be  assigned 
to  a  CRT  and  a  modem  at  the  same  time. 
In  this  way  it  would  be  unnecessary  for 
your  program  to  output  a  character  to 
both  devices  because  the  BIOS  logic  has 
enough  information  passed  to  it  to  do  it 
automatically. 

Each  segment  of  the  CHRTBL  (Table 
2,  page  116)  is  eight  bytes  long.  The  first 
six  bytes  contain  a  physical  device  name 
of  your  choice.  The  next  byte  is  used  to 
describe  whether  this  device  can  accept 
input  or  output  or  both  and  additionally 
whether  baud  rate  is  software  selectable. 
If  any  communications  protocol  is  neces¬ 
sary,  a  bit  is  set  for  that  also.  The  last 
byte  contains  the  baud  rate  for  serial 
devices.  Obviously,  this  field  would  have 


little  use  if  your  hardware  is  unable  to 
handle  software  baud  rate  selection.  Up 
to  a  maximum  of  12  table  segments  can 
be  defined;  in  all  but  a  very  large  system 
that  will  be  more  than  enough. 

Using  this  facility  is  a  two-step  proc¬ 
ess.  First,  issue  a  BDOS  function  20  that 
returns  the  CHRTBL  table  address  in  the 
HL  register  pair.  Next,  use  BDOS  func¬ 
tion  49  to  gain  access  to  the  section  of 
the  system  control  block  that  contains 
the  vector  for  the  desired  device.  The  re¬ 
turned  vector  is  then  used  to  create  a 
pointer  into  the  CHRTBL. 

This  has  been  a  very  brief  description 
of  what  could  be  a  very  important  addi¬ 
tion  to  your  system,  especially  if  you 
use  I/O  redirection  heavily.  SVj 
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OF  INTEREST 


by  Michael  Wiesenberg 


New  Multibus  Standard 

Engineers,  designers,  and  other 
electronics  industry  cognoscenti  are  all 
familiar  with  Intel’s  standard  micro¬ 
processor  bus,  the  IEEE  796  Multibus. 
Now  Intel  announces  Multibus  II,  the 
new  architecture  for  advanced  8-,  16-, 
and  32-bit  high-performance  micro¬ 
processor  systems.  Thirteen  companies 
have  joined  together  to  develop  the 
specifications  for  the  new  bus:  Ad¬ 
vanced  Micro  Devices,  Compagnie  des 
Machines  Bull,  Dataindustrier  AB, 
Hewlett-Packard,  Intel,  International 
Computer  Ltd.,  Intersil  Systems,  Ma- 
tra,  Mupac  Corp.,  Nixdorf  Computer 
Corp.,  Siemens  AG,  Tektronix,  and 
Zilog.  According  to  Intel,  “the  new 
development  and  review  effort  is  in¬ 
tended  to  accelerate  the  process  of 
industry  standardization  by  collecting 
the  views  of  manufacturers  and  users. 
Intel  expects  to  publish  Multibus  II 
specifications  in  the  second  half  of  this 
year.  The  company  will  also  provide 
Multibus  II  review  materials  to  the  re¬ 
cently  formed  Multibus  Manufacturers’ 
Group,  an  independent  organization  of 
companies  supplying  Multibus-compat¬ 
ible  products  and  service.  .  .  .  These 
modular,  processor-independent  bus 
structures  offer  capabilities  that  expand 
system  bandwidth,  enhance  multiproc¬ 
essing,  increase  system  reliability,  and 
improve  ease  of  use.” 

Standardization  and  processor- 
independent.  Those  are  the  key  words 
that  may  mean  more  compatibility 
among  future  microcomputers.  Let’s 
hope  so!  Reader  Service  No.  101. 


Apple,  Meet  CP/M; 

CP/M,  Meet  Apple 

System  One,  from  Extra  Comput¬ 
er  Corporation,  is  a  dual  processor 
(Z80/6502)  system  that  comes  with 
both  CP/M  2.2  and  Apple  DOS,  Apple¬ 
soft,  Perfect  Writer,  Perfect  Calc,  and  a 
games  package.  You  also  get  64K  RAM, 
8K  system  ROM,  16K  user  ROM,  seven 
peripheral  slots  compatible  with  Apple, 
40/80  column  display,  high  and  low  res 
graphics,  both  NTSC  and  RFmodulated 
video  outputs,  110/220  power  supply, 
sculptured  keys,  upper  and  lower  case, 
shift  lock,  and  numeric  key  pad.  The 


case  is  metal,  which  is  supposed  to 
provide  RF  interference  shielding.  And 
for  all  this  you  pay  only  $795.  Reader 
Service  No.  105. 


S-100  Process  Control 

Smartboard  RC-100  from  Auto¬ 
matic  Micro  controls  and  checks  the 
states  of  up  to  16  remote  relay  switches, 
to  turn  on  and  off  and  monitor  light¬ 
ing,  appliances,  electrically  controlled 
heating  and  cooling  devices,  or  entire 
electrical  circuits.  You  get  optically 
isolated  I/O,  zero  voltage  switching  for 
extended  relay  contact  life,  and  port 
or  memory  mapped  addressing.  You 
also  get  an  on-board  8035  CPU  and 
four  status/command  registers.  Use  it 
with  GE  RR8  remote  control  relays 
(latching  relays  able  to  switch  loads  up 
to  20  amperes,  with  states  that  are  un¬ 
affected  by  power  outages).  You  can 
control  all  the  board’s  features  from 
your  S-100  computer  with  a  BASIC 
program,  or  an  external  2716  or  2732 
EPROM  permits  custom  programming. 
For  $495  you  get  the  board,  documen¬ 
tation,  and  application  software  exam¬ 
ples.  Reader  Service  No.  109. 


A  Real  Black  Box 

Black  Box  SAM+  Centronics,  a 
Status  Activity  Monitor  from  Black 
Box  Corporation,  reconfigures,  patch¬ 
es,  monitors,  and  tests  all  active  inter¬ 
face  leads  on  Centronics- compatible 
parallel  equipment.  This  so-called 
break-out-box  gives  direct  access  to 
all  active  signal  and  ground  leads  of 
the  interface  to  ease  trouble-shooting. 
Power  comes  from  the  interface  to 
which  the  unit  attaches  with  two  fe¬ 
male  connectors  and  a  12-inch  male- 
to-male  ribbon  cable.  The  Black  Box 
permanently  monitors  Data  Strobe, 
Bits  1  through  8,  Acknowledge, 
Busy,  Paper  Empty,  Select,  OSCXT, 
Input  Prime,  and  Fault.  Other  leads 
can  be  tested  for  ground  presence  and 
pulse  by  patching  into  four  spare 
LEDs.  You  also  get  negative  and  posi¬ 


tive  pulse  detector  circuits  to  locate 
and  identify  intermittent  pulses,  and 
two  inverters  to  invert  Strobe  or  Ac¬ 
knowledge  lines.  It  costs  $225,  and 
you  get  a  one-year  warranty.  Black 
Box  will  also  send  you  a  free  catalog. 
Reader  Service  No.  103. 


Color  It  Blue 

You  don’t  have  to  pay  an  upper 
extremity  and  a  lower  appendage  for  a 
full-screen  editor  with  multiple  win¬ 
dowing  for  the  IBM  PC,  XT,  and  com¬ 
patible  clones.  Blue,  from  Symmetric 
Software,  uses  full  color  (and  also 
works  fine  in  monochrome),  simul¬ 
taneously  edits  multiple  files,  offers 
on-line  help,  has  macros,  formats  with 
embedded  commands,  does  all  the 
stuff  standard  with  most  word  proc¬ 
essors,  is  not  copy  protected,  and  costs 
$150,  or  just  the  manual  for  $35,  or 
a  demo  disk  for  $10.  Reader  Service 
No.  111. 


Color  It  8 

Eight-pen  plotters  are  coming 
down  in  price.  Strobe’s  M260,  pre¬ 
viously  introduced  as  a  six  pen  plotter, 
now  has  eight,  which  it  changes  auto¬ 
matically  under  program  control  for 
unattended  multicolor  output.  Resolu¬ 
tion  is  500  steps  per  inch.  You  also  get 
an  RS232C  interface,  IK  buffer,  upper¬ 
case  and  lower-case  character  sets,  in¬ 
cluding  foreign  language  characters, 
and  graphics  software  for  bar,  pie,  and 
line  graphs.  All  this  for  $995.  You  can 
get  the  Enhanced  Business  Graphics 
software  package  for  plotting  graphs 
from  VisiCalc  and  SuperCalc  files  and 
from  data  entered  at  the  keyboard. 
Strobe  says  that  over  30  other  popular 
graphics  packages  from  other  compa¬ 
nies  also  support  Strobe  plotters,  and 
most  of  these  are  adding  drivers  for 
the  M260.  Strobe  has  also  lowered  the 
prices  on  its  M100  and  M200  single¬ 
pen  plotters  to  $595  and  $695,  respec¬ 
tively.  These  plotters  and  the  graphics 
software  run  on  most  popular  micro¬ 
computer  operating  systems.  Reader 
Service  No.  113. 
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Hard -Wired  Desks 

Tired  of  bulky,  cumbersome  com¬ 
puter  desks  and  tables  that  look  like 
computer  desks  and  tables?  You  prob¬ 
ably  don’t  even  feel  comfortable  cod¬ 
ing  on  what  the  industry  terms  a  work¬ 
station.  Riverside  Furniture  has  intro¬ 
duced  four  new  computer  desks  that 
look  like  traditional  furniture.  One  of 
these  beauties  is  a  real  roll-top.  All  are 
made  of  real  wood,  with  pull-out  as¬ 
semblies  for  printers,  paper,  and  equip¬ 
ment,  interior  storage  for  programs 
and  disks,  and  totally  integrated  elec¬ 
trical  systems  with  surge  protectors 
and  circuit  breakers.  Prices  range  from 
$330  to  $1760.  Reader  Service  No. 
115. 


Can  You  Get 
a  Chocolate  MULTED? 

Search,  edit,  print,  and  manipu¬ 
late  text  in  multiple  files  without 
having  to  operate  individually  on  each 
with  MULTED  from  Compu-Draw. 
You  can  specify  equivalence  of  upper 
and  lower  case,  “wild  card”  searches, 
and  searches  with  column  position 
specified.  You  can  search  for  blank 
lines,  or  lines  not  containing  specified 
text.  You  can  also  specify  conditional 
editing,  for  example,  changing  all 
occurrences  of  “Dobbs”  to  “Dobb’s” 
only  if  the  words  “Dr.”  and  “Journal” 
also  appear  on  the  same  line.  MULTED 
automatically  backs  up  files  as  you 
work  on  them,  alternating  drives. 
MULTED  runs  on  CP/M,  in  many  disk 
formats,  and  costs  $59.  Reader  Service 
No.  117. 


Super  C  Superseded 

The  SuperSoft  C  Compiler  has 
been  updated  with  a  new  release  syn¬ 
tactically  compatible  with  Unix  ver¬ 
sion  7C,  and  adding  long  integer  and 
double  floating  point  functions,  plus 
an  extensive  library  of  functions.  This 
multipass  compiler  produces  optimized 
code,  obviating  the  necessity  for  assem¬ 
bly  code  in  most  applications.  Source 
code  can  easily  be  ported  between 
Unix  and  SuperSoft  versions  of  C. 
$275  for  CP/M-80,  and  $500  for 
CP/M-86  and  MS-DOS.  If  you  already 
have  SuperSoft  C,  you  can  get  an  up¬ 
grade  for  $100.  Reader  Service  No.  119. 
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EBZUG,  PUG,  SBAZUG 

If  you’ve  bought  one  of  those 
cute  little  Timex  computers,  and  can’t 
get  it  to  work  right,  what  do  you  do? 
It’s  hard  to  find  someone  to  service  a 
computer  that  costs  under  $100,  but 
don’t  junk  it.  Go  to  a  users’  group 
meeting.  You’ll  find  long  tables  with 
electrical  outlets.  Everyone  brings  and 
sets  up  a  system,  and  you  can  find 
plenty  of  people  to  help  you  debug 
your  problems.  You’ll  also  get  hints  on 
new  and  efficient  programming  tech¬ 
niques,  demos  of  peripherals  that  you 
never  thought  you  could  hook  up  to 
such  a  tiny  machine,  bargain  software, 
tips  on  where  to  buy  equipment  at 
the  lowest  prices,  and  probably  make 
new  friendships.  In  the  Bay  Area,  the 
East  Bay  Timex/Sinclair  Users’  Group 
(EBZUG)  meets  the  third  Thursday  of 
each  month  at  7:30  p.m.  at  the  Ber¬ 
keley  West  Branch  Library  near  the 
corner  of  University  and  San  Pablo. 
Yearly  dues  are  $  1 5  for  full  newsletter 
and  library  privileges,  $10  for  the 
newsletter  only,  and  $8  for  student 
(through  high  school).  The  Peninsula 
Users’  Group  (PUG)  meets  the  third 
Sunday  of  each  month  at  1  p.m.  at 
Peninsula  Hospital,  1783  El  Camino, 
Burlingame.  The  South  Bay  Area  Ti¬ 
mex/Sinclair  Users’  Group  (SBAZUG) 
meets  from  7  to  10  p.m.  the  last  Tues¬ 
day  of  each  month  at  Dysan’s  north 
entrance  by  the  loading  dock,  5401 
Patrick  Henry  Dr.,  Santa  Clara.  The 
three  together,  publish  the  newsletter, 
Timelinez.  Reader  Service  No.  127. 


Free  Turtle  Alphabet 

To  introduce  you  to  their  news¬ 
letter,  The  National  Logo  Exchange  is 
offering  to  readers  of  DDJ  a  free  Logo 
listing  that  draws  alphabet  letters  in 
any  size  or  orientation.  Send  SASE 
to  DDJ  ABC’s,  c/o  The  National  Logo 
Exchange,  Box  5341,  Charlottesville, 
VA  22905.  The  newsletter,  for  teachers 
who  use  Logo  in  the  classroom,  is 
published  September  through  May, 
and  costs  $25  per  year  in  the  U.S., 
Canada,  and  Mexico.  Elsewhere,  add 
$5.  Reader  Service  No.  121. 


Two-Bits’  Worth 

For  your  Timex-Sinclair  1000, 
“at  last,”  they  say,  “computer  games 
designed  especially  for  women.”  Work¬ 
ing  Mother’s  Dilemma  from  2 -Bit 
Software  is  a  package  of  four  games 
for  the  Harried  Housewife  (one  of  the 
games),  including  Carfool,  testing  your 
ability  to  use  the  least  gas  while  errand¬ 
running  about  town,  and  “dazed  search 
for  your  car  in  the  parking  lot  of 
Shopping  Mall.”  $14.95  each  (Califor¬ 
nians  add  6%  tax).  Reader  Service  No. 
125. 


Time  Works  on  Commodore 

Who  says  you  can’t  use  your  com¬ 
puter  to  balance  your  checkbook?  If 
you  have  a  Commodore  64,  you  can 
get  Electronic  Checkbook  from  Time¬ 
works,  for  recording,  sorting,  and 
balancing  your  checkbook;  or  an  edu¬ 
cational  game,  Dungeon  of  the  Algebra 
Dragon;  or  Programming  Kit  I,  a 
teacher  of  BASIC  and  game  and  pro¬ 
gram  design.  Each  program  costs 
$24.95.  Reader  Service  No.  123. 


$800  Daisy 

The  DWP-210  Daisy  Wheel  Printer 
from  Radio  Shack  is  code-compatible 
with  Scripsit,  has  a  standard  parallel 
interface  and  serial  interface  compati¬ 
ble  with  the  Color  Computer,  prints 
10-  or  12-pitch  or  proportional  spacing, 
and  comes  with  carbon  ribbon  and  a 
10-pitch  wheel.  Radio  Shack  claims 
200  words  per  minute  for  the  printer, 
which  sounds  impressive,  until  you 
realize  that  most  printers  are  rated  in 
characters  per  second.  Let’s  see,  the 
average  word  has  about  six  letters,  and 
1200  characters  divided  by  60  seconds 
is,  yes,  20  cps.  You  can  also  get  the 
DWP  Bidirectional  Tractor  Feed  Kit 
for  $149.95.  They  neglected  to  tell  us 
if  you  can  use  the  printer  with  other 
computers,  so  you  should  check. 
Reader  Service  No.  107. 


Letters 

(Continued  from  page  10) 

2a+b  is  divisible  by  7.  The  rule  for  cast¬ 
ing  out  nines  was  known  to  Avicenna 
(980-1037).  Leonardo  of  Pisa  (Fibonacci) 
indicated  the  tests  for  7  and  11.  The 
problem  was  “solved”  (the  quotes  are 
necessary  for  reasons  suggested  below)  in 
sweeping  generality  as  early  as  Blaise  Pas¬ 
cal,  and  is  discussed  at  some  length  by 
Gauss  in  the  Disquisitiones  Arithmeticae. 

I  am  sure  that  Gordon  did  a  reasona¬ 
ble  literature  search;  but  I  am  also  sure 
that  the  texts  consulted  were  oriented 
toward  the  practical  needs  of  persons 
doing  computation  —  Abramowitz  and 
Stegun,  the  CRC  table,  college  algebra 
texts. . .  that  sort  of  thing.  Except  for  the 
easiest  cases  (divisibility  by  2,  3,  5,  11, 
and  certain  multiples  of  these)  the  digit- 
based  divisibility  checks  are  not  of  any 
practical  computational  use  because  of 
the  labor  they  involve.  This  means  quite 
simply  that  the  checks  will  not  be  dis¬ 
cussed  in  books  oriented  toward  compu¬ 
tation.  However,  the  techniques  that  Gor¬ 
don  described  are  standard  fare  in  any 
undergraduate  number  theory  class,  and 
are  usually  discussed  there  in  full  general¬ 
ity. 

Even  though  the  techniques  are  not 
computationally  useful,  they  are  mathe¬ 
matically  interesting,  and  do  have  some 
specialized  computational  uses.  For  inter¬ 
ested  readers  of  DK Dobb’s  Journal,  I  will 
try  to  outline  the  ideas 'involved. 

Following  the  usual  notation,  let  us 
write  a=b  (mod  p)  [read:  “a  is  congruent 
to  b  modulo  p”]  if  a  and  b  leave  the  same 
remainder  upon  division  by  p,  or  equiva¬ 
lently  if  p  divides  (a-b)  evenly.  The  small¬ 
est  non-negative  integer  c  such  that  c=a 
(mod  p)  will  be  called  the  residue  of  a 
(mod  p). 

In  order  to  keep  the  discussion  sim¬ 
ple,  assume  that  p  is  a  prime.  Then  it  is 
possible  to  show  that  if  a  is  a  number  not 
divisible  by  p, 

ar  =  as  (mod  p) 

if  the  quantity  (r-s)  is  divisible  by  (p-1) 
[this  is  the  “little  theorem”  of  Fermat  - 
the  less  said  about  the  “great  theorem,” 
the  better] .  The  condition,  although  suf¬ 
ficient,  is  not  necessary: 

2Z  s  2s  (mod  7). 

When  the  condition  is  necessary  —  i.e., 
when  any  consecutive  (p-1)  powers  of  a 
are  distinct  (mod  p)  —  then  a  is  called  a 
primitive  root  (mod  p).  Primitive  roots 
(mod  p)  always  exist  for  any  p,  but  there 
is  no  procedure  (apart  from  trial  and 
error)  that  will  allow  us  to  say  whether  a 
given  number  a  is  a  primitive  root  (mod  p) 
for  a  given  p.  This  last  problem  —  the 
“primitive  root  problem”  —  is  extremely 
difficult,  and  has  defied  the  best  efforts 
of  many  of  the  most  talented  mathema¬ 
ticians  of  the  last  three  centuries.  It  is 


not  even  known  whether  any  given  num¬ 
ber,  say  2  or  10  (the  two  bases  we  are 
most  likely  to  be  interested  in),  is  a  primi¬ 
tive  root  for  an  infinite  number  of  primes. 

For  any  given  a,  primitive  root  or 
not,  we  can  define  a  number  called  the 
period.  This  is  the  number  of  consecutive 
powers  of  a  that  one  must  compute 
before  the  residues  start  repeating.  For 
example,  the  powers  of  2  (mod  7)  are  1, 
2,  4,  1,  2,  4,  1,  ...  so  the  period  of  2 
(mod  7)  is  3.  A  primitive  root  has  period 
(p-1)  by  definition. 

Now,  let  us  consider  the  divisibility 
question.  For  any  positive  integer  b  >  1, 
a  non-negative  integer  a  has  a  unique  rep¬ 
resentation, 
n 

a=  2  akbk, 

k=0  K 

where  the  a  are  non -negative  integers  be¬ 
tween  0  and  (b  — 1 ),  and  the  high-order 
coefficient  isn’t  zero.  The  base-b  repre¬ 
sentation  of  a  is  then  just  anan_!.  .  .  a^o- 
A  digit-based  divisibility  test  for  the  prime 
p  (I  will  not  apologize  for  using  the  word 
digit)  seeks  necessary  and  sufficient  con¬ 
ditions  on  the  ak  so  that  p  will  divide  a, 
or  in  the  language  of  congruences, 
n 

^2^  akbk  =  0  (mod  p). 

But  from  the  last  congruence,  it  is  clear 
that  we  need  only  consider  the  residues 
of  powers  of  b.  These  will  repeat  after 
some  number  of  times  (the  period),  so  we 
end  up  with  a  criterion  of  the  form 

n 

k2Q  akBk  =  0  (mod  p), 

where  the  Bk  are  the  residues  of  .the  cor¬ 
responding  powers  of  b. 

An  example  in  base  10  should  make 
this  all  clear.  Modulo  11 ,  the  powers  of  10 
are  1,  10,  1,  10,  1,  10, ...  .  Thus,  the  cri¬ 
terion  for  a  base-10  integer  to  be  divisible 
by  11  is 
n 

2  akBk  =  0  (mod  11), 

k=0 

where  =  1  for  even  k,  and  =  10  for 
odd  k. 

But  the  expression  in  the  Bk  gives  a 
new  number  a'  which  it  is  easy  to  see 
must  be  smaller  than  a.  If  the  original  a 
was  divisible  by  11  then  so  is  a'  (that’s 
what  3  o  means),  so  we  can  repeat  the 
procedure,  giving  us  another  number  a" 
that  is  smaller  than  a'  and  that  is  also  di¬ 
visible  by  11.  We  can  continue  in  this  way 
until  finally  we  end  up  with  a  number 
smaller  than  1 1  in  absolute  value.  But  the 
only  number  smaller  than  11  in  absolute 
value  that  is  divisible  by  1 1  is  zero  —  thus 
the  congruence  turns  into  an  equality. 

We  can  simplify  the  criterion  by  not¬ 
ing  that  10  is  congruent  to  -1  (mod  11), 
so  we  could  have  used  -1  in  place  of  10  to 
give  us  our  new  numbers  a',  a",  ....  This 
says  that  if  we  start  at  the  units  digit  and 


subtract  the  tens  digit,  add  the  hundreds 
digit,  subtract  the  thousands  digit,  and  so 
on  —  and  then  take  absolute  values,  and 
repeat  the  procedure  as  often  as  necessary 
to  get  a  number  smaller  than  1 1  in  abso¬ 
lute  value  —  the  original  number  will  be 
divisible  by  11  if  and  only  if  our  final 
anwer  is  0.  This  is  the  familiar  rule  for 
casting  out  elevens. 

Readers  might  find  it  instructive  to 
try  the  same  reasoning  on  divisibility  by  3 
(casting  out  threes).  The  rule  for  casting 
out  nines  is  similar,  although  a  slight 
modification  of  the  theory  is  needed 
since  9  is  not  prime. 

The  problem  that  comes  up  in  the 
general  case  is  that  it  is  not  known  what 
the  period  of  10  (or  2,  for  machine  arith¬ 
metic  in  binary)  is  for  arbitrary  primes  p. 
This  is  for  all  practical  purposes  the  prim¬ 
itive  root  problem  for  b  =  10  (or  b  =  2 ) 
and,  as  was  said  before,  that  problem  is 
quite  intractable.  This  complicates  the 
theoretical  analysis,  although  it  does  not 
interfere  with  setting  up  a  divisibility 
criterion  for  any  given  p  as  long  as  we  are 
willing  to  compute  all  the  residues  of  at 
most  (p-1)  powers  of  10  (or  whatever). 
Even  so,  a  little  experimentation  will 
show  that  the  resulting  criteria  are  not 
necessarily  convenient  (try  divisibility  by 
17  in  base  10). 

Persons  interested  in  pursuing  this 
subject  further  may  consult  any  standard 
undergraduate  number  theory  text. 

Yours  truly, 

John  Kahila 

217  Rock  Harbor  Road 

Orleans,  MA  02653 

An  Address  Correction  for  ACG-NJ 

Attn:  Editor 

We  were  happy  that  you  gave  a  review 
of  PISTOL—  Portably  Implemented  STack 
Oriented  Language  —  in  your  February 
issue.  I  would  like  to  correct  the  address 
of  the  Amateur  Computer  Group  of  New 
Jersey  (ACG-NJ)  from  which  potential 
users  of  this  public  domain  software  may 
obtain  an  8-inch  diskette.  The  diskette  is 
available  from  the  Special  Interest  Group 
in  Microcomputing  (SIG/M)  of  the  ACG- 
NJ,  which  is  located  at:  SIG/M,  P.O.Box 
97,  Iselin,  NJ  08830.  PISTOL  currently 
exists  as  SIG/M  Volume  059  release  1.0 
and  SIG/M  Volume  114  as  release  2.0. 
The  cost  of  the  diskette  is  $6.00  ($5.00 
plus  $1.00  shipping).  International  costs 
are  an  additional  $8.00  (U.S.  currency) 
per  order. 

Please  be  patient  when  ordering  since 
this  is  a  voluntary  organization  dedicated 
to  making  available  the  best  CP/M  and 
PCDOS/MSDOS  public  domain  software. 
Sincerely, 

William  S.  Chin 
Chairman  of  SIG/M 
P.  O.  Box  97 
Iselin,  NJ  08830 
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LETTERS 


Getting  Double  Density 
on  your  Xerox  820 

Dear  Editor, 

I  would  like  to  pass  along  a  little  in¬ 
formation  that  I  have  learned  with  regard 
to  my  Xerox  820  Version  One. 

I  purchased  the  machine  in  early 
1982  and  have  been  doing  mainly  Z80 
assembly  language  programs  for  my  own 
use  and  pleasure.  I  have  been  constantly 
irritated  by  the  limitation  of  8 1 K  of  use- 
able  space  per  minifloppy  drive  and  have 
on  occasion  thought  of  purchasing  two 
more  drives,  although  that  would  have 
been  very  difficult  for  me  to  do  as  the 
cost  is  too  much  and  the  Computerland 
from  whom  I  bought  the  Xerox  no  longer 
carries  Xerox. 

Well  anyway,  also  being  distraught 
by  the  lack  of  software  for  it,  I  bought  a 
cheap  Osborne  game  to  see  if  I  could  read 
it  onto  the  Xerox  —  reasoning  that  if  Os¬ 
borne  can  read  Xerox  disks,  then  Xerox 
(with  sufficient  manipulation)  could  read 
Osborne  disks. 

It  did  not  work.  Doing  everything  I 
could  with  the  disk  attribute  tables 
effected  no  read.  I  kept  receiving  a  “data 
overrun”  error  from  BIOS  (not  BDOS). 

Well,  the  Xerox  has  a  monitor  that 
is  external  to  CP/M  and  I  eventually  tried 
to  read  sectors  off  the  Osborne  with  it  (it 


has  a  read  command);  I  got  the  same  er¬ 
ror,  but  it  turns  out  it  actually  was  read¬ 
ing  in  128  bytes  of  data  from  the  Osborne 
diskette. 

To  make  a  long  story  short,  I  found  a 
location  in  the  monitor  RAM  that  was  set 
to  a  %80  (hex)  and  for  the  heck  of  it 
changed  it  to  zero,  and  lo  and  behold, 
the  Xerox  monitor  happily  read  256 
bytes  of  data  for  a  sector  read  off  of  the 
Osborne  disk  (it  seems  the  Osborne  has 
256  byte  physical  sectors). 

The  place  in  question  is  OFF65H  or 
%FF65,  which  might  differ  on  other 
820-I’s.  I  found  that  I  could  change  it  in 
CP/M  and  have  it  read  also.  Well,  what  this 
all  means  is  that  I  could  double  the  den¬ 
sity  of  the  Xerox  without  spending  any 
money  at  all  (although  I  do  count  my 
time  as  money),  I  changed  the  disk  for¬ 
matter  program  with  DDT  to  alter  this 
location  and  ended  up  with  Xerox  disk¬ 
ettes  that  have  a  capacity  of  184K  bytes 
of  storage. 

There  is  a  catch,  though.  I  will  have 
to  write  a  new  BIOS  and  write  some  util¬ 
ity  routines  to  copy  from  the  old  to  the 
new.  (The  Xerox  format  is  now  set  to  41 
tracks,  18-256  byte  sectors/track.)  I  have 
written  all  but  the  BIOS  disk  write  rou¬ 
tines  —  those  being  harder  than  the  read 
routines  —  as  BDOS  wants  128  bytes  and 


the  hardware  supports  256  bytes  and  I 
might  end  up  having  to  do  a  read  in  order 
to  effect  a  write. 

Well,  I  hope  that  someone  out  there 
might  find  this  information  of  use.  I 
suspected  that  it  might  be  possible  as  the 
820-1  that  I  own  has  SA400L  drives, 
which  sometimes  are  described  as  double¬ 
density  drives. 

Thomas  Kellar 
3104  Hassler  St. 

Dayton,  OH 

Moaning  and  Groaning 
About  CP/M 

Dear  Dr.  Dobb, 

While  Bill  Potter  is  “Moaning  and 
Groaning  about  MS-DOS”  (July  1983 
DDJ,  Letters,  page  10),  it  is  interesting 
that  he  put  some  changes  in  CP/ M’s  SUB¬ 
MIT  and  XSUB  by  disassembling  them 
and  (apparently)  adding  some  machine 
language  patches.  I  didn’t  know  that 
modifying  CP/M  is  so  easy.  (It  is  also 
interesting  that  Mr.  Potter  is  spending 
considerable  time  improving  CP/ M’s  utili¬ 
ties,  but  does  not  see  fit  to  “moan  and 
groan”  about  CP/M.) 

I  believe  that  the  code  which  imple¬ 
ments  the  MS-DOS  batch  facility  is  in  the 
module  COMMAND.COM,  rather  than  in 


Dr.  Dobb's  in  Istanbul 

Dear  Dr.  Dobbs,  \ 

Our  official  Dr.  Dobb’s  T-shirts  drew 
many  appreciative  stares  on  our  recent 
visit  to  Istanbul,  Turkey.  That’s  the  Blue 
Mosque  behind  us  (see  photo  at  right). 

The  microcomputer  revolution  has 
yet  to  hit  Istanbul  (video-rental  clubs  are 
the  current  craze)  but  we  did  meet  some 
young  Turks  who  are  in  the  vanguard  of 
the  micro  movement  and  who  devour 
everything  in  print  on  the  subject  and 
revere  Dr.  Dobb's  Journal. 

Soon,  the  world. 

Your  faithful  reader, 

Steve  Rank 

1260  Monument  Blvd. 

Concord,  CA  945 18 
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the  DOS  itself.  Modification  by  disassem¬ 
bly  and  patching  might  be  possible, 
though  probably  rather  difficult. 

MS-DOS  2.0  has  conditional  state¬ 
ments  and  looping  in  its  batch  files,  and 
also  supports  I/O  redirection.  This  latter 
feature  allows  a  program  to  read  its  key¬ 
board  input  from  a  disk  file  (and/or  write 
its  CRT  output  to  a  disk  file)  and  is  one 
of  the  major  features  missing  from  CP/M. 
Thus  a  command  in  a  batch  file  can  speci¬ 
fy  a  disk  file  to  be  used  in  place  of  the 
keyboard  input,  which  gives  the  same 
capability  as  CP/M’s  XSUB.  Note  that 
the  use  of  a  separate  file  for  input  pre¬ 
vents  a  command  from  reading,  as  input, 
lines  that  are  intended  to  be  commands. 

I  find  it  a  little  strange  to  be  defend¬ 
ing  MS-DOS,  since  it  is  basically  a  CP/M 
derivative,  and  I  regard  CP/M  to  be  a 
poorly  designed  and  very  primitive  oper¬ 
ating  system.  At  least  MS-DOS  is  not  an 
exact  copy.  My  own  major  “moan  and 
groan”  about  MS-DOS  is  its  lack  of  a 
DUMP  command. 


NEC  PC8001 /Epson  MP80 
User  Groups  Anyone? 


Dear  Editor: 

Are  there  many  NEC  PC8001 /Epson 
MP80  users  out  there  who: 

•  Have  unresolved  questions/cannot 
get  English  manuals/ have  useful  in¬ 
formation  not  covered  in  the  English 
manuals? 

•  Know  of  individuals/companies  offer¬ 
ing  programs  —  in  NEC  5‘4-inch  disk 
format  —  to  run  under  CP/M  or  other 
DOS? 

•  Know  of  companies  offering  NEC  PC 
compatible  cards  —  or  would  like  to 
know  of  such  companies? 

•  Know  of  any  active  user  groups,  or 
would  like  to  form  a  users’  group? 

If  there  are  enough  people  with  the 
same  problem,  maybe  I  can  send  Dr. 
Dobbs  a  (translated )  answer. 


A  Cross  Assembler 
for  the  MC68000 

Dear  Sir: 

The  Software  Review  article  by  Steve 
Newberry  on  page  108  of  your  August 
issue  states  that  there  are  no  cross  assem¬ 
blers  for  the  MC68000  which  run  on  the 
8080. 

We  would  like  to  draw  your  attention, 
and  that  of  your  readers,  to  the  fact  that 
farbware  has  been  offering  just  such  an 
assembler  since  June  of  1983.  This  assem¬ 
bler  is  compatible  with  the  assembler  pro¬ 
vided  by  Motorola  for  their  development 
systems  and  offers  conditional  assembly, 
macros,  and  structured  programming 
facilities. 

Farbware  intends  to  offer  a  series  of 
cross  assemblers  for  16 -bit  microproces¬ 
sors  such  as  the  16032  in  the  future. 

We  have  been  subscribing  to  Dr. 
Dobb’s  for  some  years  now,  and  have 
every  issue  back  to  the  first.  The  quality 
of  your  publication  is  excellent. 

Sincerely, 

David  Farb 
President 
Farbware 
1329  Gregory 

Wilmette,  IL  60091  SSj 


Sincerely, 

Jim  Howell 
5472  Playa  Del  Rey 
San  Jose,  CA  95123 


Yours  truly, 

Keith  S.  Wilkinson 
CPO  Box  1748 
Tokyo,  JAPAN  100-91 


EDITORIAL 

DDJ  Pays  Authors! 


Truth  truly  is  stranger  than  fiction.  Starting  this  month, 
DDJ  will  be  paying  for  articles! 

Most  of  you  are  probably  aware  that,  until  now,  our 
authors  have  generously  contributed  their  material  for  the 
satisfaction  of  sharing  information  with  fellow  computer 
enthusiasts  and  of  seeing  the  effect  it  had  on  the  work  of 
others.  These  are,  of  course,  potent  incentives,  and  we  as¬ 
sume  that  their  influence  will  remain  strong.  We  are  well 
aware,  however,  of  the  substantial  effort  required  to  pro¬ 
duce  the  articles  and  programs  that  we  publish.  We  are  very 
grateful  to  all  those  who  have  so  willingly  shared  their  la¬ 
bors  and  expertise  with  their  colleagues  and  fellow  readers. 

Because  we  know  what  it  takes  to  produce  a  manu¬ 
script,  we  have  wanted  to  pay  authors  for  some  time.  Non¬ 
profit  status  being  the  mixed  blessing  that  it  is,  we  were 
forced  to  learn  the  virtues  of  patience.  Now  we  are  moving, 
and  we  expect  to  have  the  entire  payment  program  firmly 
in  place  by  the  New  Year. 

We  would  like  to  thank  all  our  supporters  and  adver¬ 
tisers  who  have  helped  make  this  possible.  And  we  are 
pleased  to  be  able  to  express  our  thanks  to  our  authors  in 
more  concrete  terms.  Give  us  a  call  or  drop  us  a  line  to  find 
out  the  details. 

*  *  * 


We  have  scheduled  the  February  1984  issue  as  our  tele¬ 
communications  specialty  issue.  For  those  interested  in  sub¬ 
mitting  material,  some  of  the  topics  that  we  are  considering 
are  local  area  networking,  security  in  telecommunications, 
protocols,  and  micro-to-mainframe  hookups.  This  list  is 
certainly  suggestive  rather  than  exhaustive.  If  you  have  a 
topic  that  you  are  interested  in  writing  about,  let  us  know 
soon.  We  have  set  the  copy  deadline  at  November  10,  1983. 
Since  the  timeframe  on  this  one  is  pretty  tight,  interested 
people  should  contact  us  at  (415)  323-3111  for  details. 
This  part  of  the  field  is  growing  quickly,  and  we  expect  this 
special  issue  to  provide  some  timely  information  on  several 
of  its  facets. 

*  *  * 

In  closing,  we  would  like  to  thank  all  those  who  re¬ 
sponded  to  our  request  in  August  for  technical  referees. 
The  turnout  was  very  good  and  we  are  well  on  our  way  to 
having  the  review  board  completely  set  up. 
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DR.  DOBB’S  CLINIC 


by  D.  E.  Cortesi,  Resident  Intern 


P-System  Help  Wanted 

At  last,  avisitor  to  the  Clinic!  Dwight 
Irving,  of  the  University  of  Idaho,  sent  us 
the  following  plea. 

“I  have  been  trying  to  install  a  UCSD 
p-System  Version  IV.O  from  Softech  Mi¬ 
crosystems  and  have  encountered  several 
problems.  The  computer  has  a  Z80  proces¬ 
sor,  64K  RAM,  a  CompuPro  Disk  1  control¬ 
ler,  and  two  8 -inch  drives.  The  operating 
system  is  CP/M  2.2  for  which  CompuPro 
supplied  its  GBBIOS. 

“I  tried  to  use  the  PASBOOT  program 
to  boot  up  the  CP/M  adaptable  system. 
Since  the  p-System  disks  were  single  den¬ 
sity  it  was  necessary  to  recalibrate  [re-log- 
in?  DEC  ]  the  drives  before  trying  to  read 
the  secondary  booter;  it  refused  to  be 
read  anyway. 

“I  next  obtained  a  working  p-System 
disk  from  another  computer.  I  changed 
the  PASBOOT  program  to  include  disk 
routines  from  the  CompuPro  program. 
The  attempt  to  boot  was  only  partly  suc¬ 
cessful;  the  secondary  booter  was  read  in 
but  an  error  “Can’t  find  SYSTEM. PAS¬ 
CAL”  occurred.  The  same  disk  will  boot 
up  with  another  computer;  the  skew 
values  I  used  are  correct  for  this  disk. 
Also,  no  error  occurred  during  the  BIOS 
disk  routines. 

“Both  CompuPro  and  Softech  tell 
me  the  problem  is  a  nonstandard  BIOS 
and  that  I  will  have  to  use  the  full  adapt¬ 
able  system.  I  would  appreciate  any  infor¬ 
mation  that  would  help  in  writing  the 
SBIOS  for  the  Disk  1  Controller  or  on 
how  to  fix  it  so  that  I  could  use  the  CP/M 
adaptable  system.” 

We  don’t  know  zip  about  the  p- 
System,  but  surely  some  reader  does. 
What  are  the  steps  by  which  the  p-System 
comes  up  from  a  CP/M  base,  and  where 
do  you  twiddle  the  hardware-dependent 
parts  of  it?  All  letters  will  be  passed  on  to 
Dwight  and  summarized  here. 

Also  PC  Help 

W.  B.  Koehler,  of  Foster  City,  Cali¬ 
fornia,  also  has  a  question.  “I  have  been 
told  that  on  the  IBM  PC  one  can  manage 
cursor  control  via  a  BASIC  Print  statement 
using  the  CHR$  function.  Apparently  the 
string  begins  with  the  ESC  (027)  charac¬ 
ter  followed  by  some  screen  positioning 
scheme.  Can  you  find  out  the  truth  of 
this  matter?” 

That’s  certainly  how  you  manage  the 
IBM  printer  functions,  and  CP/M-86 
supports  cursor  control  using  escape 


sequences.  But  if  it’s  true  of  MSDOS,  it 
must  be  something  added  in  DOS  2.0. 
Readers? 


Double  Amplification 

Allan  L.  Behler,  Jr.,  of  Newport, 
North  Carolina,  writes  at  length  on  the 
problems  of  numeric  precision  in  BASIC. 
He  warns  that  PRINT  USING,  although 
it  may  produce  a  correct  display  of  a 
slightly  inaccurate  number,  has  no  effect 
on  the  variable  being  displayed.  “I.E.,  if 
you  print  out  1000  double-precision  num¬ 
bers  such  as  134.12  with 

PRINT  USING  “#####.##” 

the  individual  numbers  may  appear  cor¬ 
rect,  but  their  total  in  storage  can  be  off 
by  as  much  as  0.06.  I  know  because  the 
first  business  software  I  wrote  did  just 
this,  and  caused  some  ugly  phone  calls.” 

Then  Allan  leads  up  to  an  interesting 
problem  and  a  useful  solution  through  a 
series  of  experiments.  Try  them  out  your¬ 
self  to  see  if  you  get  the  same  results. 
Begin  in  immediate  execution. 

DEFDBL  A 
A  =  134.12 
PRINT  A 

134.1199951171875 
Aha!  Now  round  it  up. 

A1  =  INT(  A *100  +0.51  ) 

PRINT  A 
13412 

A  is  still  carried  as  double-precision  float¬ 
ing  point,  but  its  value  is  integral,  and  a 
correct  representation  of  the  desired 
number  (times  100). 

A2  =  Al/100 
PRINT  A2 

134.12 

As  if  by  magic,  the  untruncated  value 
appears.  Allan  next  tries  it  as  a  function. 

10  DEFFNRD(X)=INT(X*  100+0.51) 
20  DEFDBL  A 

30  A=134.12  :  PRINT  A 

40  A1  =  FNRD(A)  :  PRINT  A1 
50  A2=A1/100  :  PRINT  A2 

RUN 

134.1199951171875 

13412 

134.12 

Allan  notes  that  you  could  use  this 
function  to  force  all  numbers  to  double¬ 
precision  integral  values,  process  them  in 
that  format,  and  then  print  them,  divided 
by  100,  with  PRINT  USING  for  rounding. 


However,  let’s  try  the  whole  job  in  one 
function. 

NEW 

10  DEFFNRD(X)=INT(X*100+0.5 1)/100 
20  DEFDBL  A 

30  A=134.12  :  PRINT  A 

40  A=FNRD(A)  ;  PRINT  A 
RUN 

134.1199951171875 

134.1199951171875 

“Now,”  says  Allan,  “I  have  to  admit  that 
this  had  me  going  for  a  year.  The  function 
would  work  fine  for  single  precision  but 
not  for  double  precision.  Then  a  friend 
solved  it  for  me  in  about  12  seconds  (you 
know  the  type  of  friend  I  mean).” 

NEW 

5  Z#=100 

10  DEF  FNRD(X)=INT(X*100+0.51)/Z# 
20  DEFDBL  A 

30  A=134.12  :  PRINT  A 

40  A=FNRD(A)  :  PRINT  A 
RUN 

134.1199951171875 

134.12 

“The  use  of  a  double-precision  divisor  of 
100  makes  the  funtion  work  for  both 
single- and  double-precision  numbers.” 

In  Search  Of .  .  . 

We  ain’t  assembly  language  freaks.  We 
don’t  like  assembly  language.  It’s  a  tedi¬ 
ous,  error-prone  medium  for  expressing 
one’s  ideas,  and  its  use  ensures  nonporta¬ 
ble  code.  You  can  ameliorate  the  tedium 
and  error-proneness  with  a  good  library 
of  standard  subroutines,  but  there’s  noth¬ 
ing  you  can  do  about  the  nonportability. 
And  that,  when  the  market  for  software 
is  fragmented  by  so  many  incompatible 
systems,  is  a  killer. 

So  what  we,  and  probably  every  pro¬ 
grammer,  want  is  a  good,  medium-level, 
systems  programming  language.  A  lan¬ 
guage  needs  two  characteristics  to  be 
“good”  for  this  use.  It  has  to  be  a  good 
notation  for  the  expression  of  algorithms, 
and  it  has  to  compile  to  object  modules 
that  are,  at  worst,  twice  as  large  and  half 
as  fast  as  well-written  assembly  language. 

It  isn’t  impossible,  you  know.  For 
some  years  we  made  daily  use  of  PL/S,  an 
IBM  proprietary  language  for  systems 
programming  on  the  System/370  series. 
PL/S  met  both  criteria.  It  was  a  tolerably 
expressive  notation  (basically  PL/I  with 
extensions);  and  the  compiler  did  exten¬ 
sive  global  optimization,  so  it  built  object 
code  that  was  not  an  affront  to  the  soul. 
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But  that  is  all  nostalgia  now;  we  want  a 
systems  programming  language  for  per¬ 
sonal  computers.  As  far  as  we  can  tell, 
there  are  none. 

For  a  while,  we  had  hopes  for  Pascal. 
It  isn’t  a  great  notation  for  systems  pro¬ 
gramming,  but  it  can  be  stretched  to  do 
the  job.  Furthermore,  its  syntax  lends 
itself  to  optimal  object  code.  Pascal  is 
designed  so  that  the  writer  has  to  tell  the 
compiler  all  sorts  of  things  about  the  way 
variables  are  used.  An  optimizing  compiler 
could  use  that  information  to  produce 
good  code. 

Unfortunately,  Pascal’s  syntax  is  also 
designed  to  permit  a  simple,  one-pass, 
recursive-descent  compiler  —  and  that  is 
what  all  the  personal  compilers  are.  The 
techniques  of  global  optimization  have 
been  well-known  for  a  decade;  Pascal’s 
syntax  is  admirably  suited  to  global  opti¬ 
mization;  yet  we  don’t  have  any  optimiz¬ 
ing  Pascals.  They  all  produce  code  that  is 
dumb,  dumb,  dumb. 

Looking  to  C 

All  the  buzz  is  that  C  is  the  answer  to 
our  prayers,  an  expressive  notation  that 
compiles  to  efficient  code;  so  we  recently 
gave  it  a  try.  Keith  Coy,  C  guru  and  presi¬ 
dent  of  PicoNet,  a  local  CP/M  group, 
recommends  Aztec  C,  so  that’s  what  we 
bought.  It’s  a  clean  implementation,  he 
says,  closely  compatible  with  Unix  C. 
It  is  all  those  things.  We  don’t  recall  he 
said  it  was  fast,  and  it  isn’t.  Most  compar¬ 
ative  benchmarks  put  the  Aztec  imple¬ 
mentation  in  the  second  rank  for  object 
size  and  speed;  so  we  figured  that  if  our 
programs  came  out  a  little  bit  slow,  we 
could  move  to  a  better  compiler  without 
changing  languages.  In  the  meantime,  reli¬ 
ability  and  standardization  would  be  nice 
to  have. 

So  we  wrote  our  first  C  programs. 
The  first  nontrivial  one  was  a  filter  that 
accepted  an  Aztec  C  link  map,  sorted  it 
into  ascending  order  by  addresses,  and 
wrote  it  out.  You  can  read  the  final  ver¬ 
sion  in  Listing  One  (page  14). 

The  lirst  thing  we  learned  about  C  is 
that  it  takes  some  learning.  Take  the  use 
of  the  “item”  structure  in  Listing  One, 
for  instance.  It  is  not  intuitively  obvious 
that 

p  — >  addr 

has  the  value  of  an  unsigned  integer,  while 
the  expressions 

p  — >id 

&(p  —>  id) 

are  identical  and  yield  the  address  of  a 
character  string.  These  discoveries  were 
made  in  the  course  of  two  hours’  work 
getting  scanf  to  do  what  we  wanted  it  to 
do.  At  one  point  we  peeked  into  stdio.h, 
saw  this, 

int  (  *SYSVEC[MAXVEC]  )  () 
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and  were  sidetracked  for  90  minutes  with 
Kernighan  and  Ritchie,  working  out  what 
it  meant.  (It  means  SYSVEC  is  an  array 
of  MAXVEC  elements,  each  a  pointer  to 
a  function  that  returns  an  integer.  You  read 
it  outward  from  the  center  in  a  spiral.) 

The  pristine  eloquence  of  our  original 
program  has  been  somewhat  distorted. 
The  constant  IGNORAD  was  introduced 
because,  for  unknown  reasons,  scanf 
returns  one  line  of  garbage  before  it  dis¬ 
covers  EOF.  We’re  probably  doing  some¬ 
thing  wrong,  or  maybe  we  found  a  bug. 
That’s  the  trouble  with  new  languages; 
you  can’t  tell  your  own  mistakes  from 
the  compiler’s. 

Then  there  was  the  baffling  system 
hang,  which  persisted  until  we  renamed 
our  output  function  from  “write”  to 
“display.”  There’s  a  runtime  function 
named  “write,”  it  seems,  which  wasn’t 
linked  because  ours  was  present.  Is  that  a 
bug?  Or  would  an  experienced  C  user 
know  not  to  use  the  name  “write”? 

Warming  the  Molasses 

In  the  first  version,  output  was  pro¬ 
duced  with  a  printf  call  very  like  the 
scanf  call  that  gets  the  input.  We  got  it 
working,  and  it  was  slow.  Not  merely 
slow  compared  to  assembly  language,  but 
slow  as  molasses.  Given  its  own  link  map 
(200  lines,  about  2500  bytes),  it  took  68 
seconds  to  complete.  That’s  intolerable  in 
a  filter- type  program,  so  we  stuck  the 
message  lines  in  “main()”  to  find  out 
what  was  taking  all  the  time.  It  broke 
down  this  way : 

•  load  from  disk,  set  up  in  and  out 
files:  5  seconds 

•  reading:  7  seconds 

•  sorting:  1 .2  seconds 

•  writing:  55  seconds 

The  Quicksort  routine  was  quick  enough. 
Reading  data  at  350  bytes/second  was 
slow,  but  the  real  boggier  was  writing. 
*What  in  the  world  afflicted  output? 

To  find  out,  we  used  the  SID  debug¬ 
ger  with  its  HIST  utility  routine.  This 
useful  combination  is  described  at  length 
in  the  SID  manual.  HIST  collects  a  count 
of  instruction  addresses  during  a  trace 
and  displays  them  as  a  histogram  of 
execution  density.  Listing  Two  (page  16) 
shows  a  typical  display.  It  is  a  coarse 
measure  of  execution  density  over  the 
entire  span  of  the  object  module.  Listing 
Three  (page  18)  is  the  result  of  zooming 
in  on  a  smaller  span  of  code.  It  has  a  fine 
enough  grain  that  individual  runtime 
routines  can  be  picked  out. 

When  you  look  at  Listings  Two  and 
Three,  bear  in  mind  that  the  code  that 
was  generated  from  Listing  One  ends  at 
0x0598.  All  the  rest  is  from  the  runtime 
library. 

HIST  showed  a  particularly  hot  spot 
in  a  routine  called  “ldiv.”  By  examining 


the  source  of  the  runtime  code,  we  dis¬ 
covered  that  ldiv  was  the  long-integer 
divide  routine.  Further  prowling  revealed 
that  printf  used  a  long-integer  divide  to 
generate  each  digit  of  an  output  integer. 
Every  execution  of 


printf(“%04x  %s”,p  — >  addr,p  — >id) 

caused  four  long  divides.  That’s  why  we 
wrote  the  routine  named  “xprint”  in 
Listing  One.  Its  use  eliminated  the  long 
divides,  and  that  took  8  seconds  off  the 
output  time,  bringing  it  from  55  seconds 
to  47. 

We  found,  however,  that  the  cold 
molasses  was  actually  in  the  disk  output 
code.  When  stdout  was  not  diverted  to  a 
file,  but  rather  allowed  to  come  to  the 
screen,  the  output  phase  took  only  5  sec¬ 
onds,  not  47  (we  had  previously  shaved 
off  8  seconds,  reducing  it  from  13  to  5 
seconds).  Further  zooms  with  HIST 
turned  up  a  broad  hot-spot  encompassing 
the  library  routines  for  sequential  disk 
output.  These  are  clearly  less  than  opti¬ 
mal.  We  don’t  know  what  is  wrong  with 
them;  they  may  be  calling  the  BDOS  to 
read  back  the  current  sector  on  every 
byte  of  output  or  maybe  we  made  some 
obscure  user  error,  as  with  using  the  name 
“write.”  We  don’t  plan  to  find  out. 


Disappointed  Again 

We  don’t  care  because  the  experi¬ 
ment  had  already  failed  before  that  last 
problem  turned  up.  The  C  notation,  de¬ 
spite  its  difficulties,  is  certainly  usable, 
even  elegant.  It’s  great  fun  to  eliminate 
lines  of  code  by  embedding  increments, 
decrements,  and  assignments  in  the  argu¬ 
ments  of  functions.  But  consider:  even  if 
the  example  program  wrote  to  disk  as  fast 
as  it  reads,  it  would  still  be 

•  a  16KB  program  from  a  2KB 
source  file 

•  with  a  throughput  of 

160  bytes/second 

A  hypothetical  assembly  program  would 
be  a  2KB  object  file  with  a  throughput 
near  1000  bytes/second  (if  challenged, 
we’ll  write  it  to  prove  the  point). 

Consider  also  the  quality  of  code 
generated  by  this,  a  typical  one-pass  com¬ 
piler  that  is  within  a  factor  of  2  of  the 
current  state  of  the  industry.  The  object 
file  is  full  of  things  like 

XCHG 

INX  H 

INX  H 

XCHG 

to  increment  the  DE  register,  and 

LX1  H,0000 

XCHG 

11 


to  put  zero  in  it.  A  simple  peephole  opti¬ 
mizer  would  doubtless  bring  Aztec  C  into 
competition  with  its  faster  rivals.  But 
peephole  optimization  wouldn’t  fix  the 
grosser  blunders  it  shares  with  all  one-pass 
programs,  like  recalculating  a  value  that 
already  exists  in  one  of  the  registers,  or 
calculating  an  expression  on  every  pass  of 
a  for-loop  even  though  the  elements  of 
the  expression  aren’t  changed  in  it.  That 
requires  global  optimization. 

Until  somebody  produces  a  genuine 
optimizing  compiler  for  C  (or  Modula  2, 
or  what-have-you),  the  software  develop¬ 
er  will  be  faced  with  a  choice  between 
writing  quick,  small,  machine-dependent 
code  in  assembly  language,  or  writing 
sluggish,  bloated,  portable  code  in  C.  It’s 
a  nasty  dilemma,  and  we  wish  somebody 
would  produce  the  compiler  that  would 
get  us  off  its  horns. 


( Listings  begin  on  page  1 4 ) 
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Dr.  Dobb’s  Clinic  (Text  begins  on  page  10) 

Listing  One 


(/include  "stdio.h" 

//define  MAXIDS  500 
//define  MAXLEN  9 
//define  IGNORAD  0x0000 

struct  item  {/*  one  symbol  table  entry  */ 
unsigned  addr; 
char  id [MAXLEN]; 

}; 


int  readsym(s) 
struct  item  *s; 

{  /*  read  one  symbol  table  item  from  stdin  */ 
s->addr  =  IGNORAD; 

return  (  scanf("/t4x  $8s"  ,&(s->addr )  ,s->id)  ); 

} 

int  readall(sa) 
struct  item  sa[]; 

{  /*  read  all  symbol  table  items  from  stdin,  count  them,  report  full  »/ 
int  n; 
n  =  0; 

while  (  readsym(sa+n)  !=  EOF  )  { 

if  (  (sa+n)->addr  !=  IGNORAD  )  { 
if  (  (++n)  ==  MAXIDS  )  { 

fprintf (stderr,"too  many  items,  %d  will  be  used\n" , MAXIDS) ; 
break; 

} 

} 

} 

return  (n); 

} 

swap(p,q) 

struct  item  #p,  *q; 

{/*  exchange  items  p  and  q  */ 
struct  item  t; 
t  =  *p;  *p  =  *q;  *q  =  t; 

} 

quick(lo,  hi,  p) 
struct  item  p [  ] ; 
int  lo,hi; 

{/#  sort  an  array  of  items  using  standard  quicksort  idiom  */ 
int  i,  j ; 
unsigned  pivot; 
if  (lo  <  hi)  { 

pivot  =  p[hi].addr; 

for  (i=lo,j=hi;i<j;){ 

while  (i  <  j  &&  p[i].addr  <=  pivot  )  ++i; 
while  (j  >  i  &&  p[j].addr  >=  pivot  )  — j; 
if  (i  <  j)  swap ( &p[i],&p[j]); 
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} 

swap(&p[i],&p[hi]) ; 
quick(lo,i-1 ,p) ; 
quick(i+1 ,hi ,p) ; 

} 

} 

xprint(n) 
unsigned  n; 

{/*  display  hex  address  the  hard  way  */ 

static  char  digits[l6]  =  {  '0' , ' 1 ' , '2' , '3' , '4' , '5' ,  '6 ' ,  '7 ' , 

'8V9VAVBVCVDVEVF'  }; 

int  c; 

for  (c=12;c>=0;c-=4) 

putc(digits[  (n  »  c)  &  OxOOOf  ],stdout); 

} 

display(p  ,n) 
struct  item  *p; 
int  n; 

{/*  write  n  symbols  starting  at  p  */ 
for  (  ;  n>0  ;  — n,  ++p  )  { 
xprint (p->addr ) ; 
printfC"  $s\n" ,p->id) ; 

} 

} 

main( ) 

{ 

struct  item  table [MAXIDS ] ; 
int  count ; 

fprintf (stderr , "reading\n" ) ; 

count  =  readall (table ) ; 
fprintf (stderr , "sorting\n" ) ; 

quick(0, count-1 , table) ; 
fprintf (stderr, "writing\n") ; 
display (table, count) ; 

} 


Listing  Two 


#c. initial 

TYPE  HISTOGRAM  BOUNDS  100,4100 

.INITIAL  =  C521 

.COLLECT  =  C524 

.DISPLAY  =  C527 

#uffff , .collect 

—ME-  A=BE  B=0535  D=00CA  H=A8BB  S=A8B1  P=0593  CALL  0486  .DISPLAY 
*0518 

#uffff , .collect 

- E-  A=5F  B=048B  D=A8AC  H=A8EF  S=A8A7  P=05l8  ORA  A 

*05D3 


End  Listing  One 


(Continued  on  page  18) 
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Dr.  Dobb’s  Clinic  (Listing  continued,  text  begins  on  page  10) 

Listing  Two 


#c. display 
HISTOGRAM: 

ADDR  RELATIVE  FREQUENCY,  LARGEST  VALUE  =  9C03 

•  •  •  • 

0400  ****** 

0500  ************************************* 

0600  ********** 

0700  *************************************************************** 
•  •  •  • 

1E00  *** 

1F00  ** 

2000  ********** 

2100  ** 

•  •  •  • 

2A00  ****** 

•  •  •  • 

3500  ********************* 

36OO  ***************** 

3700  **************** 

•  •  •  • 

3900  **** 

3A00  ** 

•  •  •  • 

4100  » 


Listing  Three 

c. initial 

TYPE  HISTOGRAM  BOUNDS  400,800 

.INITIAL  =  C521 

.COLLECT  =  C524 

.DISPLAY  =  C527 

#uffff, .collect 

-  A=01  B=36FA  D=A86l  H=A86l  S=A86l  P=05D3  SPHL 

*36F4 

#c  .display 
HISTOGRAM: 

ADDR  RELATIVE  FREQUENCY,  LARGEST  VALUE  =  1DCA 

•  •  •  • 

0410 
0420  * 

0430  ** 

0440  * 

0450  ** 

0460  * 

0470  ** 

0480 

0490 

04A0 

04B0 

04C0 

04D0 

04E0 


End  Listing  Two 
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04F0  ** 

0500  ** 

0510  ** 

0520 

05B0  ************* 

05C0  ************************** 

05D0  ************************************ 

05E0  ***** 

05po  ******* 

0600  ******* 

0610  *** 

0620  ** 

0630  ******** 

0640  ***** 

•  •  •  • 

0700  *************** 

0710  *********** 

0760  ***** 

0770  *********** 

0780  ******************************************** 

0790  * 

07A0  ********** 

07B0  *************************************************************** 

07C0  *** 

0800  * 


End  Listing  Three 
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A  Kernal  for  the  MC  68000 


Sixteen  bits  and  nowhere  to  go! 
Being  a  “hardware”  type  I  natural¬ 
ly  had  to  have  a  16 -bitter  as  soon  as 
I  could  manage  it.  After  letting  the  dust 
settle  a  bit  I  decided  to  go  with  the  68000 
processor  from  Motorola.  The  board  I 
chose  (the  M68K  from  Educational 
Microcomputer  Systems)  has  Motorola’s 
Macsbug  monitor  in  PROM,  but  other 
than  that  I  had  no  software  to  run  my 
new  friend. 

Several  months  later,  after  punching 
out  a  cross-assembler  in  C  for  software 
development,  I  was  ready  to  start  writing 
code.  But  what?  I  have  always  been 
fascinated  by  real-time  software,  and 
multiple  tasking  is  supposed  to  be  one  of 
the  things  that  the  68000  is  designed  for. 
So,  enter  the  kernal. 

The  Kernal 

A  kernal  is  a  software  device  that  dis¬ 
tributes  CPU  time  among  concurrently 
running  processes.  A  process  is  an  individ¬ 
ual  task,  or  program,  that  runs  asynchro¬ 
nously  with  other  tasks.  Since  the  kernal 
is  continuously  switching  between  tasks 
at  a  high  rate  of  speed,  it  appears  to  a 
human  observer  that  all  tasks  are  running 
simultaneously.  Responding  to  both  hard¬ 
ware  interrupts  and  software  traps,  the 
kernal  decides  which  process  gets  the 
next  use  of  the  CPU,  how  long  it  may  use 
it,  and  in  what  order  other  processes  must 
wait. 

System  resources  other  than  the  CPU 
may  also  be  shared  by  creating  device 
manager  processes  for  each  port,  disk 
drive,  and  so  on.  The  process  controls 
the  device,  carrying  out  requests  for  de¬ 
vice  usage  from  other  processes.  It  also 
may  return  either  data  or  status  informa¬ 
tion  to  the  requesting  process. 

As  an  example,  a  device  manager 
would  be  written  to  control  each  terminal 
port  on  a  system.  A  user  program  wishing 
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to  do  I/O  would  generate  a  software  trap 
to  the  kernal,  passing  a  request  for  either 
input  or  output.  The  data  would  typically 
be  placed  into  a  common  buffer  before 
an  output  request,  or  taken  from  the 
buffer  after  an  input  request. 

Upon  receiving  such  a  request  from 
a  process,  the  kernal  would  stop  it  and 
save  all  necessary  registers  in  memory.  It 
would  then  start  the  device  managing 
task  and  pass  the  request  to  it.  This  task 
would  initiate  the  I/O  and  give  control 
back  to  the  kernal.  The  kernal  would 
then  run  some  arbitrary  task  until  receiv¬ 
ing  an  interrupt  from  the  hardware  signal¬ 
ling  that  the  I/O  is  complete.  It  then 
awakens  the  manager,  which  passes  con¬ 
trol  back  to  the  requesting  process  along 
with  a  result  message  of  the  I/O  process. 

Although  this  seems  quite  compli¬ 
cated  on  the  surface,  it  allows  more  effi¬ 
cient  use  of  the  CPU  since  it  is  not  wast¬ 
ing  time  while  waiting  on  the  relatively 
slow  speed  of  port  hardware.  It  also 
creates  a  level  of  system  protection  since 
the  device  manager  may  refuse  to  grant 
requests  based  on  permission  algorithms, 
reservations,  etc. 

The  68000 

The  Motorola  68000  offers  all  the 
hardware  features  necessary  for  efficient 
implementation  of  such  a  kernal.  It  allows 
a  total  of  192  user- generated  interrupts, 
either  software  or  hardware  generated. 
Each  such  interrupt  has  a  corresponding 
four-byte  vector  in  the  first  page  of  mem¬ 
ory  that  holds  a  jump  address  to  a  service 
routine.  It  also  has  two  different  operat¬ 
ing  modes:  supervisor  and  user.  When  in 
user  mode,  certain  instructions  may  not 
be  used,  allowing  direct  hardware  protec¬ 
tion  of  sensitive  instructions.  Further¬ 
more,  if  utilized,  the  hardware  can  address 
memory  so  that  no  process  running  in 
user  mode  can  even  access  memory  set 
aside  for  the  supervisor  state/ code. 

The  assembler  syntax  used  in  the  list¬ 
ing  (page  22)  is  fairly  straightforward, 
consisting  of  mnemonics  and  pseudo-ops 
as  defined  by  Motorola.  Comments  are 
preceded  by  an  asterisk  (*)  on  comment- 
only  lines,  or  may  follow  the  operand 
fields  of  statements  without  the  asterisk. 
The  “,b”,  “.w”,  and  “.1”  extensions  of 
mnemonics  specify  byte,  word,  and  long 
word  data  sizes.  The  pound  sign  (#) 
marks  an  immediate  value. 

The  Code 

The  code  as  presented  is  far  from  a 


complete  system.  It  is  a  workable  starting 
point,  demonstrating  the  features  of  a 
multi-tasking  kernal.  First  1  will  explain 
what  it  does  as  written,  then  I’ll  go  into 
various  ways  it  might  be  modified  for  par¬ 
ticular  uses. 

The  first  set  of  equates  defines  the 
memory/port  map.  It  should  be  noted 
that  the  68000  uses  memory-mapped  I/O, 
thus  allowing  any  instruction  that  manip¬ 
ulates  memory  to  also  access  a  port.  The 
next  section,  commented  out,  describes 
the  exception  (hardware  and  software 
interrupt)  vector  table  utilized  by  the 
68000.  When  implementing  this  kernal, 
you  would  set  whichever  of  these  vectors 
the  application  required. 

Beyond  this  is  the  beginning  of  the 
kernal  data  area  (800hex).  A  maximum 
of  eight  concurrent  processes  are  allowed, 
with  three  being  set  up  at  the  start.  Fol¬ 
lowing  this  is  a  process  descriptor  defini¬ 
tion.  It  contains  a  pointer  to  the  next 
process  descriptor,  a  priority  flag,  and 
space  to  store  the  entire  register  set  of  the 
CPU.  The  final  lines  set  aside  additional 
descriptor  space  for  each  of  the  possible 
tasks. 

A  series  of  pointers  is  then  allocated. 
Running  is  a  pointer  to  the  process  de¬ 
scriptor  of  the  currently  running  task. 
Ready  is  a  pointer  to  the  head  of  the 
queue  of  tasks  waiting  for  CPU  time. 
Dead  is  a  pointer  to  a  queue  of  unused 
process  descriptors.  Conditions  is  an  array 
of  pointers,  one  for  each  process,  in 
which  the  process  descriptor’s  address  is 
stored  when  it  is  “sleeping,”  i.e.,  when  it 
is  waiting  to  be  restarted  by  another  task. 
Finally,  device  1  and  device  2  point  to 
queues  of  tasks  waiting  on  those  devices. 

The  first  part  of  the  kernal  is  its 
initialization  entry  point.  It  sets  up  its 
stack,  initializes  the  needed  exception 
vectors,  and  queues  the  processes  into  the 
running  and  ready  slots.  It  then  goes  on 
to  initialize  three  very  simple  tasks  for 
demonstration  purposes.  This  includes 
setting  a  program  counter,  stack  pointer, 
and  status  register  value  for  each.  Re¬ 
maining  unused  descriptors  are  put  into 
the  dead  queue  for  future  use.  Finally, 
the  stack  pointer  and  status  register  values 
for  the  first  task  are  pushed  onto  the 
stack.  It  is  then  started  with  an  rte  in¬ 
struction.  This  is  the  standard  method  of 
causing  the  68000  to  return  to  a  task  that 
generated  an  exception.  The  task  will 
then  run  until  an  exception  (interrupt  or 
trap)  occurs. 
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The  Kernal  Body 

The  body  of  the  kernal  has  three 
entry  points.  The  major  entry  point  is 
slice.  It  is  addressed  by  the  exception  vec¬ 
tor  reserved  for  hardware  clock  interrupts. 
In  my  case  this  amounts  to  a  button  on 
the  front  panel  for  clock  simulation 
purposes.  The  wait  entry  point  is  called 
(with  a  trap  #10)  by  a  task  wishing  to 
sleep  while  awaiting  some  occurrence 
within  the  system.  The  condition  (i.e., 
the  condition  slot)  it  wishes  to  wait  on  is 
passed  in  data  register  7.  The  correspond¬ 
ing  signal  entry  point  (trap  #11)  is  used 
by  another  task  to  cause  awakening  of  a 
task.  The  particular  condition  it  wishes  to 
signal  is  passed  in  data  register  7.  The 
slice  _trap  entry  (trap  #12)  is  used  by  a 
process  to  give  up  the  CPU  to  the  next 
waiting  process. 

Other  routines  should  be  accessed 
only  from  within  the  kernal.  Store _ 
runner  and  restore _  runner  save  and  re¬ 
store  the  machine  state  when  switching 
tasks.  Switch  is  used  by  the  kernal  to 
place  the  running  task  into  the  ready 
queue  and  retrieve  a  waiting  task. 

The  Tasks 

The  tasks  I  have  written  so  far  do 
nothing  more  than  give  a  visual  display  of 
their  existence.  Task  one  prints  a  series  of 


ASCII  one’s  (1)  then  waits  on  condition  1 
to  become  true.  Task  two  prints  a  series 
of  two’s  (2)  then  waits  on  condition  2. 
Task  three  prints  a  series  of  three’s  (3), 
signals  task  two,  then  signals  task  one. 
This  whole  process  continues  until  a 
“clock”  interrupt  occurs.  This  clocking 
causes  the  current  task  to  suspend  and 
the  next  task  to  execute.  The  device 
managers  for  the  ports  described  above 
have  not  yet  been  written. 

Modifying  For  The  Real  World 

Obviously  the  first  changes  to  make 
would  be  to  remove  the  fake  tasks  and 
write  useful  replacements.  A  real  system 
clock  would  be  added  to  cause  time  slic¬ 
ing.  The  address  of  the  slice  routine  in 
the  kernal  would  be  placed  in  the  hard¬ 
ware  interrupt  vector  slot  used  by  the 
clock. 

If  the  kernal  were  to  be  used  for  real¬ 
time  control  of  specific  hardware  devices, 
individual  tasks  would  be  created  that 
manage  each  device.  This  would  include 
handshaking  via  interrupts  and  assignment 
of  relative  priorities  with  the  priority 
word  in  each  descriptor. 

If  used  as  the  basis  of  an  operating 
system,  a  user  interface  task  would  be 
needed,  as  well  as  device  managers  for 
each  port.  Processes  for  a  file  system  and 
a  media  storage  manager  would  be  needed. 


The  operating  system  written  in  Small-C', 
published  in  the  March  ’83  DDJ,  would 
be  an  interesting  starting  point. 

It  would  be  possible  to  save  task 
switching  time  by  saving  only  those  regis¬ 
ters  known  to  be  used  by  user  processes. 

The  process  descriptor  allocation 
could  be  made  completely  dynamic  if  it 
were  to  be  kept  just  above  each  task’s 
stack  pointer.  This  scheme  would  only 
work  with  simpler  hardware  that  didn’t 
map  memory  according  to  the  current 
operating  mode,  since  the  descriptor  nor¬ 
mally  accessed  from  supervisor  mode 
would  now  reside  in  user  memory. 

This  software  is  free  of  restrictions  as 
to  non-commercial  use  and  distribution. 
Commercial  use  without  author’s  permis¬ 
sion  is  forbidden.  I  will  try  to  keep  the 
code  on-line  on  my  dial-up  system  around 
the  time  it  is  published.  1  also  intend  to 
keep  various  public  domain  68000  utili¬ 
ties  available  for  callers.  The  system  is 
accessible  24  hours,  seven  days  a  week,  at 
(303)  781-4937.  Public  domain  code, 
ideas,  and  discussion  about  the  68000  are 
all  welcome. 

»»J 

( Listing  begins  below ) 


EV8CSSOOO  Kernal  Listing  (Text  begins  on  page  20) 


************************************************************************* 


*  * 

A  Kernal  for  the  MC  68080  processor  * 

*  * 

*  (C)  Cooyright  .1.983  Steve  Passe,  all  rights  reserved  * 

*  * 


##*##*#*#**#****#***«•#*#****##**#*****##*##**#******###♦****#**##*##****# 


0009  000000 

0000  0000 

0010  000000 

0000  0800 

0011  000000 

0000  7000 


first _page: 

equ  $0  except  ion  vec 

tors 

kernal  : 

equ  $800  init  entry  to 

kerna 1 

kernal_data: 

equ  $7000  user  scratch 

memory  on  erns 


0013  000000 

0000  0000 


user  _sr_  mask : 

equ  0  no  trace/user 

/lowest  int. 


0015  000000 

0000  0064 

0016  000000 

0000  0080 


auto_v_ i nt : 

eou  $64  address  of  an 

to  vet or  #1 

trao_0 : 

eou  $80  address  of  tr 


22 


Dr.  Dobb’s  Journal,  November  1983 

647 


MC68000  Kernal  Listing  (Listing  continued,  text  begins  on  page  20) 

ao  #0  vector 

0018  000000  port : 


0019  000000 


0003  FF0 1 


0003  FF30 


port  : 

eau  *03ff01 

#1  status  on  erns 
int_l_ack : 
eau  $03ff30 

1  (cl oc k )  int  ack 


level 


mao  of  exception  vectors,  not  used  when  running  under  rnacsbug 

ora  first  oaoe+8  first  8  cast  in  silicon 


* 

dc.  1 

error .vect  or 

£ : 

bus  error 

* 

dc.  1 

error_vectc*r 

3 : 

address  error 

* 

dc.  1 

error  .vector 

4: 

illegal  instruction 

* 

dc.  1 

error_ vector 

5 : 

divide  by  zero 

* 

dc.  1 

error _vect or 

6: 

out  of  bounds 

* 

dc.  1 

error. vect or 

7: 

overflow 

* 

dc.  1 

error  .vect  or 

8: 

privilege  violation 

* 

dc.  1 

error_vector 

9: 

trace  routine 

* 

dc.  1 

error  ..vect  or 

10: 

1010  psuedo  code 

* 

dc.  1 

error_vect  or 

1 1 

1111  pseudo  code 

* 

vectors  1£  thr 

u  £3  reserved  by  Motorola, 

tc 

■  be 

* 

really  safe  I 

suppose  you  should  init  them. 

.  . 

■* 

* 

org  f irst _oage+$5c 

address  of  vector  #£4 

* 

dc.  1 

error _vect or 

£4 

s  p  ur  i  ous  i  nt  err  u  ot- 

* 

dc.  1 

error_vect or 

izl5 

#1  autovector,  system  c 

* 

dc.  1 

error _vect or 

ir.'S 

level  £  int.  autovector 

* 

dc.  1 

error_vector 

£7 

level  3  int.  autovector 

* 

dc.  1 

error_vector 

£8 

level  4  int.  autovector 

* 

dc.  1 

error_vector 

£9 

#5  autovector,  serial  o 

* 

dc.  1 

error .vect or 

30 

#6  autovector,  parallel 

•* 

dc.  1 

error_vector 

31 

#7  autovector,  abort  sw 

* 

dc.  1 

error .vect or 

3£ 

trao  #0  vector 

* 

dc.  1 

error_vector 

33 

trap  #1  vector 

* 

dc.  1 

error .vector 

34 

t r a d  #£  vector 

* 

dc.  1 

error_vect  or 

35 

trap  #3  vector 

* 

dc.  1 

error.vector 

36 

trap  #4  vector 

* 

dc.  1 

error.,  vect  or 

37 

trap  #5  vector 

* 

dc.  1 

error  ..vector 

38 

trap  #6  vector 

* 

dc.  1 

error.vector 

39 

trao  #7  vector 

* 

dc.  1 

error _vect or 

40 

trao  #8  vector 

* 

dc.  1 

error.vect or 

41 

traD  #9  vector 

* 

dc.  1 

wait 

4£ 

#10,  kernal  wait  entry 

*• 

dc.  1 

si gnal 

43 

#11,  kernal  signal  entr 

* 

dc.  1 

si  ice .trao 

44 

#1£,  kernal  slice  entry 

* 

dc.  1 

error.vector 

45 

trap  #13  vector 

* 

dc.  1 

error  vector 

46 

trap  #14  vector 

comment  out  trap  #15  init  to  retain  rnacsbug  console  i/o  trap. 

dc.  1  error  vector  -47:  trao  #15  vector 


vectors  48  thru  S3  reserved  by  Motorola,  to  be 
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really  safe  I  suppose  you  should  init  them  also 


* 

* 

* 

* 

* 

* 


gonna  cheat  here,  64-255  are  for  hardware  interrupts  that 
generate  their  own  vector  number.  If  your  hardware  can 
generate  such  interrupts  these  must  also  be  initialised. 


0080  007000  7000 

* 

*  maximum  #  of  processes  in  the 

* 

0085  007000 

0000  0008 

0086  007000 

0000  0003 

* 

*  the  process  descripters,  need 

* 

0092  007000 
0093  007000 

0000  0000 
0094  007000  0000  7214 
0095  007004 

0000  0004 
0096  007004  0063 
0097  007006 

0000  0006 
0098  007006  0000 
0099  007008 

0000  0008 
0100  007008  0000  0D6C 
0101  00700C 

0000  000C 

0102  00700C  0000  0000 

0103  007010  0000  0000 
0104  007014  0000  0000 
0105  007018  0000  0000 


org  kernal_data 

kerna 1 


orocesses : 

ecu  8  #  of  Drocesse 

s  supported 

runners : 

enu  3  #  of  running 

processes 

one  for  each  possible  active  process 


process  _ 

1  : 

next_proces5 : 

equ 

*-process_l 
t  process 

offset  to  nex 

dc.  1 

Drc<cess_x 

points  to  nex 

t  process  in 

oueue 

pr i or i t  y 

: 

eou 

♦-process _1 
cess  priority 

offset  to  pro 

dc.  w 

99 

his  process 

priority  of  t 

sr_slot : 

eau 

*-orocess_l 
tus  rep. 

offset  to  sta 

dc.  w 

0 

us  register 

value  of  stat 

pc_slot : 

eau 

*— orocess_l 
g.  cntr. 

offset  to  pro 

dc.  1 

dummy 

value  of  prog 

ram  counter 

d0_slot : 

eau 

*-process_l 

copy 

offset  to  d© 

dc.  1 

0 

value  of  d0  f 

or  this  process 

dc.  1 

0 

value  of  dl 

dc.  1 

0 

value  of  d2 

dc.  1 

0 

value  of  d3 

(Continued  on  next  page) 
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0106 

0070 1C 

0000 

0000 

dc.  1 

0 

va  1  ue 

of 

d4 

0107 

007020 

0000 

0000 

dc.  1 

0 

value 

of 

d5 

010Q 

007024 

0000 

0000 

dc.  1 

0 

value 

of 

d& 

0109 

007028 

0000 

0000 

dc.  1 

0 

va  1  ue 

of 

d7 

0110 

00702C 

0000 

0000 

dc.  1 

0 

val  ue 

of 

a0  f 

or  this  process 

011  1 

007030 

0000 

0000 

dc.  1 

0 

va  1  ue 

of 

al 

01 1£ 

007034 

0000 

0000 

dc.  1 

0 

value 

of 

a2 

0113 

007038 

0000 

0000 

dc.  1 

0 

va  1  ue 

of 

a3 

0114 

00703C 

0000 

0000 

dc.  1 

0 

val  ue 

of 

a4 

0115 

007040 

0000 

0000 

dc.  1 

0 

value 

of 

a5 

01 16 

007044 

a6_slot 

• 

0000 

0044 

equ 

*-process_l 

offset 

tc 

>  a6 

copy 

0117 

007044 

0000 

0000 

dc.  1 

0 

va  1  ue 

of 

a6 

0118 

007048 

a7_slot 

: 

0000 

0048 

equ 

*-process_l 

offset 

tc 

.  a  7 

copy 

0119 

007048 

0000 

0E7C 

dc.  1 

durnrny_so 

va  1  ue 

of 

a7 

0120 

00704C 

0000 

0000 

ds 

0 

insure 

1  alignrn 

ent 

0121 

00704C 

process 

_si ze : 

0000 

004C 

equ 

*-orocess__l 

size  of  a 

i  pro 

cess  descripter 

0123 

00704C 

process 

: 

0000 

01C8 

ds.  b 

<  orocesses- 

2) * process 

_  g  i 

ze 

1  ess 

#1  &  dummy 

0125 

007214 

process 

_x  ! 

0000 

004C 

ds.  b 

process _si z 

e  dummy 

process 

0127 

007260 

process 

_space : 

0000 

02!60 

equ 

*- oroees5_l 

the  queue 

pointers. . . 

* 


0133 

007260 

0000 

0000 

running : 
dc.  1 

0 

er 

to 

running 

point 

process 

0135 

007264 

0000 

0000 

ready : 
dc.  1 

0 

er 

to 

head  of 

po  i  nt 

ready  queue 

0137 

007268 

0000 

0000 

dead : 
dc.  1 

0 

point 

er  to  head  of  dead  queue 

* 

*  conditions  (args  to  wait  and  signal),  only 

*  one  process  can  wait  for  any  one  condition 

*  in  this  version. . . 

* 


26 

650 


Dr.  Dobb’s  Journal,  November  1983 


0145  00726C  conditions: 

0000  0008  ds. 1  Drocesses  *  con 

d it  ion  slots,  one  for 
*  each  Dossible  process 

* 

*  device  1  is  acia  #1  for  this  machine 

* 

0152  0072QC  device_l: 

0000  0001  ds. 1  1  Dtr  t 

o  head  of  device  1  Queue 


* 

*  device  2  is  acia  #2 

* 

device_2: 

ds.  1  1  Dtr  t 

o  head  of  dev  ice, _2  Queue 


0158  007290 

0000  0001 


************************************************************************* 


*  * 

*  The  initial  entry  point  to  the  kernal....  * 

*  * 

*  * 

*  * 


************************************************************************* 


0168  000800  0800 


org  kernal 


0170  000800 


kernal  init: 


* 

*  setup  the  machine 

* 

0175  000800  46FC  2700 
0176  000804  2E7C  0000  7C00 

* 

*  set  the  needed  vectors 

* 

0181  000800  21 FC  0000  0902  0064 
0182  000812  21FC  0000  0E86  0074 
0183  000810  21FC  0000  0E88  0078 

0184  000822  21FC  0000  0E8O  007C 

**  this  is  temp  till  a  system  clock  is 
0186  000820  21 FC  0000  0902  007C 


move. w  #42700, sr 

no  int,  su 
move.  1  #47c00, so 

kernal  stack 


move. 1  #sl ice, auto_v_int 

hardware  clock,  vl 

move. 1  #serial_port, auto_v_int+ (4*4 
)  acia  interrupts,  v5 

move.  1  #paral lel_port,  auto_v_int+  <5 
*4)  parallel  port  int,  v6 

move. 1  #abort_button,  auto_v_int+ (6* 
4)  abort  switch,  v7 

instal led : 

move.  1  #slice,auto  v  int+<6*4) 


( Continued  on  next  page) 
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0188  000832  21FC  0000  0958  0008 


0189  000830  21FC  0000  0976  00OC 


0190  000842  21 FC  0000  09B8  00B0 


move. 1  #wait, trao_0+ ( 10*4)  kerna 
1  wait  entry,  trao  #10 
move. 1  #signal, trao_0+ ( 1 1*4)  kerna 
1  signal  entry,  #11 
move.  1  #sl ice_trap, trap_0+ ( 12*4)  (s 
oft ware)  orocess  slice,  #12 


*  initialize  and  Queue  all  the  processes... 


0195  000840  4DF8  7000 


process_l , a6 

a6  holds  otr  to  runni 


0196  00084E  2 ICE  7260 


move. 1  a6, running 

runnirm  points  to  o  1 


0197  000852  2A4E 


move. 1  a6, a5 


a5  points  0  process_l 


0198  000854  DBFC  0000  00E4 


0199  000850  21  CD  7268 


add. 1  # (runners*orocess  size),a5 


x  runners 


move. 1  a5, dead 


dead  points  0 


process  ? 


move. 1 


#process_x, ready 


0201  00085E  21 FC  0000  704C  7264 


ready  points  0  dummy 
move. 1  #orocess_2, ready 

ready  points  0  p_2 


*  init  the  dead  for  future 


0206  000866  3E3C  0213 


0207  000860  284E 


0208  00086C  4BF8  704C 


move. w  #< ( processes— 1 ) *orocess_si ze 
)-l,d7  bytes,  less  dbf 
move. 1  a6, a4 

a4  points  at  base 
lea  orocess_2, a5 

a5  points  0  process_2 


0209  000870 
0210  000870  10DC 

0211  000872  51CF  FFFC 


next _ byte: 
move. b  <a4)+,  <a5)+ 

stuff  a  byte 
dbf  d7,next_bvte 

another  bvte 


*  init  first  and  last  process  rep  values 


0216  000876  2D7C  0000  09FC  0008 


move. 1  #task_l, pc_slot (a6) 

setup  proprarn  counter 


0217  00087E  3D7C  0001  0004 


move. w  #1 , priority <a6) 


setup  priorit 
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#user_sr_mask,  sr_slot  (a6) 

setuo  status  register 

#task_l_sp, a7_slot <a6) 
setuD  stack 

Drocess_£, a5 

a5  holds  desrc.  base 
#process_£+Drocess_si ze,  (a5) 
point  to  next  Drocess 

#task_£, pc_slot (a5) 

setuo  program  counter 

#1 , priority  <a5) 

setuD  priorit 

y 

#user_sr_mask,  sr_slot  <a5) 

setup  status  register 

#task_£_SD,  a7_slot  <a5) 
setuo  stack 

#process_size,  a5 

a5  holds  desrc.  base 
#task_3, pc_slot (a5) 

setuo  oronrarn  counter 

#1 , oriority (a5) 

setuo  Driorit 

y 

#user_sr_mask,  sr_slot (a5) 

setuD  status  register 

#task_3_sp,  a7_slot  <a5) 
setup  stack 

process_K,  a5 

a5  holds  dummy  proces 

5 

#dummy, pc_slot  <a5) 

setuD  program  counter 

#user_sr_mask,  sr_slot  <a5) 

setuo  status  register 
#dummy_sp, a7_slot (a5) 
setuo  stack 


dead, a5 


dead  pointer 

(Continued  on  next  page) 
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0243  0008F8  ”E03 


0244  0008FA 

0245  0008FR  DBFC  0000  004C 


rnoveq  #processes-  < runner s+1  +  1 ) ,  d7 

rn  i  nus  i  *unners/d untrny/d 
bf 

next_dead : 

rdd.  1  #Droces5_5ize,  a5 

point  to  next  Dr --cess 


0246  000900  2B4D  FFB4 


0247  000904  51CF  FFF4 


move.  1  a5, -Droeess__si ze  (a5) 

into  last  pres. next 
dbf  d7,  next__dead 

cont inue 


*  do  for  it ! 


0252  000908  207C  0000  0B20 


0253  00090E  4E60 


0254  000910  2F3C  0000  09FC 


move. 1  #task_l_  sd,  a0 

task  1  so  into  a0.  .  . 

move. 1  a0, usd 

...then  into  user  so 
move. 1  #task_l,-  (sd) 

setuD  rte,  task  1  add 


0255  000916  3F3C  £000 


move,  w  #0,-<sp) 


and  status  ren.  valu 


0256  000910  4E73  rte 

************************************************************************* 
*  * 

*  the  body  of  the  kernal  code.  .  .  * 

*  * 

*  reg  d7  is  used  to  pass  condition  #  * 

*  reg  a6  is  reserved  by  kernal  to  keep  do inter  to  running  * 


entry  points: 


1:  wait,  trap  #10 
2:  signal,  trap  #11 
3:  slice_trap,  trap  #12 


*************************************************** ********************** 


0272  0009 1C 


kernal_body : 


0274  0009 1C 


store  runner: 


save  the  running  process  in  it’s  descrioter 


0277  0009 1C  2F0E 


0278  00091 E  2C78  7260 


0279  000922  48EE  3FFF  000C 


move. 1  a6, -(so) 

oush  a6  onto  stack 
move.  1  running,  a6 

current  runner  into  a 

6 

rnovern.  1  d0-d7/a0— a5,  d0_slot (a6) 

store  the  dat 

a  &  addr.  reas. 
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0280 

000928 

2D5F 

0044 

0281 

00092C 

3D6F 

0004 

0006 

0282 

000932 

2D6F 

0006 

0008 

0283 

000938 

2F57 

0006 

0284 

00093C 

5C8F 

0285 

00093E 

082E 

0005 

0006 

0286 

000944 

6608 

0287 

000946 

4E6C 

0288 

000948 

2D4C 

0048 

0289 

0290 

0291 

00094C 

00094E 

00094E 

4E75 

2D4F 

0048 

0292 

000952 

58ftE 

0048 

0293 

000956 

4E75 

0295 

0296 

000958 

000958 

007C 

0700 

0297 

00095C 

6 1  BE 

0298 

00095E 

CEFC 

0004 

0299 

000962 

4BF8 

726C 

0300 

000966 

2B8E 

7000 

0301 

0302 

00096ft 

00096ft 

2C78 

7264 

0303 

00096E 

21D6 

7264 

0304 

000972 

614fl 

0305 

000974 

4E73 

move. 1 

(so) +, a6_slot  <a6) 

dod  saved  a6 

move. w 

4 (so) , sr_slot (a6) 

store  status  register 

move.  1 

6 (so)  ,  pc_s 1 ot <a6) 

store  the  orogram  cou 

nt  er 

move.  1 

(sp) , 6 (so) 

Dut  return  over  sr/oc 

addq.  1 

#6,  SD 

setuo  return 

btst 

#5, sr_slot  <a6) 

were  we  supervisor  be 

fore? 

bne.  s 

is_5uoer 

yes,  don’ t  need  uso.  . 

move.  1 

usd, a4 

no,  get  users  stack  o 

o inter 

move.  1 

a4,  a7_slot (a6) 

and  Diace  in  descriDt 

er 

rts 

is_super 

: 

move.  1 

sp,  a7_slot (a6) 

Dresent  ssd  value 

addq.  1 

#4, a7_slot (a6) 

value  before  this  sub 

rout ine 

rts 

wait : 

or 

#$0700, sr 

block  interrupts 

bsr.  s 

store_ runner 

save  this  process 

mulu 

#4,  d7 

#  by  pointer  size 

lea 

condit ions,  a5 

base  of  conditions 

move.  1 

a6, 0(a5, d7) 

store  Drocess  in  cond 

i  t  i  on  x 

run  s 

move. 1 

ready, a6 

get  ready  from  queue 

move. 1 

( a6) , ready 

new  head  of  ready  one 
ue 

bsr.  s 

restore_runner 

setuo  next  process 

rte 
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0307 

0308 

000976 

000976 

007C  0700 

si gna 1 : 
or 

#$0700, sr 

0309 

000970 

CEFC  0004 

rnul  u 

block  interrupts 

#4,  d7 

0310 

00097E 

0687  0000  726C 

add.  1 

make  offset  to  condit 

ion 

#condit ions, d7 

031 1 

000984 

CF8E 

exq 

add  base  of  condition 
s 

d7,  a& 

0312 

000986 

4096 

tst.  1 

setup  indirection  on 
a& 

<a6) 

0313 

000988 

CF8E 

exg 

test  for  null 

d7,  a6 

0314 

000980 

6602 

brie,  s 

restore  prior  order 

switch 

0315 

00098C 

4E73 

rte 

if  waiting  go  for  it 

0317 

0318 

00098E 

00098E 

6 1  SC 

switch : 
bsr.  s 

store_runner 

0319 

000990 

2F07 

move. 1 

save  runner 
d7, -(so) 

0320 

000992 

49F8  7264 

lea 

ready, a4 

0321 

000996 

6150 

bsr.  s 

start  at  head  of  read 

y  aueue 

1 ink_oueue 

0322 

000998 

205F 

move. 1 

put  into  ready  aueue 
<sd) +, a5 

0323 

000990 

2C55 

move. 1 

setup  indirection  aga 
in 

<  a5) , a6 

0324 

00099C 

4295 

clr.  1 

get  the  waite 
r 

<a5) 

0325 

00099E 

61  IE 

bsr.  s 

not  waiting  anymore 
rest  ore_runner 

0326 

000900 

4E73 

rte 

restore  new  runner 

0328 

0329 

000902 

000902 

007C  0700 

si ice : 

or 

#$0700, sr 

0330 

000906 

4039  0003  FF30 

tst.  b 

block  interrupts 
int_l_ack 

0331 

0009OC 

sof t_sl 

clear  interrupt 

ice : 

0332 

0009OC 

6100  FF6E 

bsr 

store_runner 

0333 

0009B0 

49F8  7264 

lea 

save  runners  register 

s 

ready, a4 

0334 

0009B4 

6132 

bsr.  s 

start  at  head  of  read 

y  aueue 

1 ink_oueue 

link  runner  into  read 
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j- 


0335  0009B6  60B2 

0337  0009BQ 

0338  0009B8  007C  0700 
0339  0009BC  60EE 
0341  0009BE 

*  restore  runner 

* 


y  queue 
bra. s  run 

go  for  ready 

si ice_traD : 

*  entry  to  slice  from  softwa 
re 

or  #$0700, sr 

block  interruots 
bra.  s  sof t_sl ice 

restore_runner : 

* 

from  descrioter  (in  aS  when  called) 


0345  0009BE  BICE  7260 
0348  0009C2  265F 

0347  0009C4  2B6E  0048 
0348  0009C8  082E  0005  0006 

0349  0009CE  6604 

0350  0009D0  4E64 

0351  0009D2  6002 

0352  0009D4 
0353  0009D4  2E4C 

0354  0009D6 

0355  0009D6  2F2E  0008 

0356  0009DO  3F2E  0006 

0357  0009DE  2F0B 

0358  0009E0  4CEE  7FFF  000C 

0359  0009E6  4E75 


move.  1 
move. 1 

move.  1 
btst 

bne.  s 

move.  1 

bra.  s 

wa s_su per 
move.  1 

SD_set : 
move. 1 

move. w 

move.  1 
rnovern. 1 

rts 


a6, running 

record  new  runner 
(sd)  +,  a3 

save  return,  clear  st 

ack 

a7_slot  <a6) , a4 

stack  to  restore 
#5,  sr_slot (a6) 

were  we  supervisor  be 

fore? 

was_suDer 

yes,  don’ t  need  usd 

a4, usd 

...then  into  usd 

SD_set 

we  hoDe! 

a4,  sd 

ssd  =  old  SSD 

oc_slot  <a6) , - (sd) 

restore  the  program  c 

ounter 

sr_slot (a6) ,  - (sd) 

restore  status  re gist 
er 

a3, - (sd) 

restore  return 
d0_slot (a&)  ,  d0-d7/a0— a& 

restore  data  &  ad dr. 

regs. 


0361  0009E8  link_oueues 

* 

*  link  a  process  into  the  oueue  pointer  to  by  a4 

* 

0364  0009E8  264C  move. 1  a4, a3 

remember  last 


(Continued  on  page  38) 
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0365 

0009ER 

£854 

move. 1 

(a4) , a4 

next 

link  int 

o  head 

0366 

0009EC 

3E£C 

0004 

move,  w 

priority (a4) , d7 

pet 

pr i or i t  y 

into  dat  rep. 

0367 

0009F0 

BE6E 

0004 

crnp.  w 

priority  <a6) ,  d7 

compare  runni 

nq  and  head 

0368 

0009F4 

63F£ 

bis.  s 

1 ink_queue 

keeo  trying 

0369 

0009F6 

£68E 

move. 1 

a&, ( a3 ) 

1  ast 

.  next  == 

running 

0370 

0009F8 

£C8C 

move. 1 

a4,  <a6) 

(former)  runn 

i no. next  ==  link 

0371 

0009FA 

4E75 

rts 

* 

* 

the  first 

process 

0377 

0009FC 

task  1 : 

0378 

0009FC 

££3C 

0000 

0050 

move. 1 

#80. dl 

0379 

000A02 

t  1 : 

£07C 

0003 

FF01 

move. 1 

#oort , a0 
#1 

acia 

0380 

000A08 

103C 

0031 

move. b 

#’ 1’ , d0 

why? 

0381 

000A0C 

4EB8 

0E8E 

jsr 

Dut  char 

send 

it 

038£ 

000A10 

7001 

rnoveq 

#1,  d0 
enth  sec 

one  t 

0383 

000A12 

4EB8 

0E7C 

jsi' 

sleep_tenth 

kill 

t  i  me 

0384 

000A16 

51C9 

FFEA 

dbf 

dl,  t_l 

0385 

000A.1  A 

7E01 

moveq 

#1,  d7 

on  cond i t i on  one 

wait 

0386 

000A1C 

4E4A 

traD 

#10 

0387 

000A1E 

60DC 

bra.  s 

t  ask_ 1 

forev 

er 

0388 

000AE0 

0000 

0080 

ds 

1  £8 

enouo 

h? 

0389 

000BS0 

0000 

0000 

ds 

0 

e  alignment 

insur 

0390 

l7l00B£0 

task_l_sD: 

* 

the  second  process 

0398 

000B20 

task  £: 

039" 

000B20 

££3C 

0000 

0050 

move. 1 

#80. dl 

0398 

000B26 

t  £: 

207C 

0003 

FF0 1 

move. 1 

#port , a0 
#1 

acia 

0399 

000B2C 

1 03C 

003£ 

move. b 

#’ £’ , d0 

why  not ! 

0400 

000B30 

4EB8 

0E8E 

jsr 

out  char 

send 

i  t 
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0401 

000B34 

7001 

0402 

000B36 

4EB8 

0E7C 

0403 

000B3A 

51C9 

FFEA 

0404 

000B3E 

7E02 

0405 

000B40 

4E4A 

0406 

000B42 

60DC 

0407 

000B44 

0000 

0080 

0408 

000C44 

0000 

0000 

0409 

000C44 

* 

* 

the 

third 

process 

* 

£415 

000C44 

0416 

000C44 

223C 

0000 

0050 

0417 

000C4A 

207C 

0003 

FF0 1 

0418 

000C50 

1 03C 

0033 

0419 

000C54 

4EB8 

0E8E 

0420 

000C58 

7001 

0421 

000C5O 

4EB8 

0E7C 

0422 

000C5E 

51C9 

FFEA 

0423 

000C62 

7E02 

0424 

000C64 

4E4B 

0425 

000C66 

7E01 

0426 

000C68 

4E4B 

0427 

000C6O 

60D8 

0428 

000C6C 

0000 

0080 

0429 

000D6C 

0000 

0000 

0430 

000D6C 

* 

* 

the 

dummy  process 

* 

0436 

000D6C 

0437 

000D6C 

103C 

0021 

0438 

000D70 

20 7C 

0003 

FF0 1 

0439 

000D76 

4EB8 

0E8E 

0440 

000D7O 

60F0 

0441 

000D7C 

0000 

0080 

0442 

000E7C 

0000 

0000 

0443  000E7C 

* 

*  sleeD  one  tenth  second 

* 


moved 

#1,  d0 

jsr 

sleeo_tenth 

kill 

dbf 

t  i  me 
d  1 ,  t  2 

moved 

#2,  d7 

wait 

trao 

on  condition  two 
#10 

bra.  s 

task._2 

forev 

ds 

er 

128 

i  hoo 

ds 

e  so 

0 

insur 

e  alignment 
task  2  so: 

task 

move. 1 

#80.  dl 

t_3 : 

move. 1 

#Dort , a0 

aci  a 

move. b 

#1 

#’  3’  ,  d0 

jsr 

put  char 

send 

rnoveq 

it 

#1,  d0 

jsr 

sleep_tenth 

kill 

dbf 

t  irne 
d  1 ,  t  3 

rnoveq 

#2,  d7 

sinna 

trao 

1  two 
#11 

rnoveq 

#1,  d7 

si  gna 

trao 

1  one 
#1 1 

bra.  s 

task_3 

forev 

ds 

er 

128 

ds 

0 

insur 

e  alignment 
task  3  sd: 

dummy : 

move. b 

#’ ! ’ , d0 

move. 1 

why  for? 
#port . a© 

ac  ia 

jsr 

#1 

put  char 

send 

bra.  s 

it 

dummy 

forev 

ds 

er 

128 

ds 

0 

insur 

dummy_sp 

e  alignment 

(Continued  on  next  page) 
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MC68000  Kernal  Listing  (Listing  continued,  text  begins  on  page  20) 


0449 

000E7C 

sleep 

_tenth : 

0450 

000E7C 

tenth 

_constant : 

0000 

C350 

equ 

50000 

0451 

000E7C 

C0FC 

C350 

rnul  u 

#tenth_ 

constant , d0 

mult 

ply  by 

const  ant 

045£ 

000ES0 

s  t: 

51C8 

FFFE 

dbf 

d0, s_t 

0453 

000E84 

4E75 

rts 

0456 

000E86 

serial_port : 

* 

* 

process 

serial  port  interrupts 

* 

0459 

000E86 

4E73 

rte 

0461 

000E88 

paral lel_port : 

* 

* 

process 

parallel  port  interrupts 

* 

0464 

000E88 

4E73 

rte 

0466 

000E8R 

abort_button: 

li¬ 

* 

process 

the  abort  button 

* 

0469 

000E8A 

4E73 

rte 

0471 

000E8C 

error_vect  or : 

# 

* 

process 

rnisc.  vectors  called  incorrect ly. . . 

* 

code 

to  report  error 

0477 

000E8C 

4E73 

rte 

routine  to 

output  a  char  to  port  addressed  by  register  a0 

a0: 

address 

of  port 

d0 : 

byte  to 

out out 

* 


0487 

0488 

000E8E 

000E8E 

2F01 

out_char 
move. 1 

dl,  -(so) 

0489 

0490 

000E90 

000E90 

1210 

o_c : 
move. b 

save  dl 

<a0) , dl 

0491 

000E92 

0201 

0002 

and.  b 

1 oad  st  at  us 

ord 
#2,  dl 

0492 

000E96 

67F8 

beo.  s 

check  t buffer  empty 

D_C 

0493 

000E98 

1  140 

0002 

move. b 

not  empty  yet... 
d0, 2 ( a0> 

0494 

000E9C 

22  IF 

move. 1 

ready,  ship  it  put 
(so) +, d 1 

restore  dl 
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0495  000E9E  4E75 
0497  000EA0 

symbol  —  hex 

a6 _slot 

a7_slot 

a  bor t  _  b  ut  t  on 

auto_v_irit 

corid  i  t  i  ons 

d0_slot 

dead 

device_l 
device_£ 
d  urnrny 
durnrny_sp 
error_vect or 
f irst_page 
int_l_ack 
is_super 
kerna 1 
kernal_body 
k.ernal_data 
kernal_init 
1 i nk_queue 
next_byte 
next  dead 
next_process 

D_e 

paral lel_port 
pc_slot 

Dort 

pr i or i t  y 

process_ 1 

process_£ 

orocess_si ze 

proeess_spaee 

process__x 

processes 

put_char 

ready 

rest or e_ runner 
run 

runners 

running 

s_t 

serial _ port 
si gnal 
sleeo_tenth 
s  1  i  ce 

si ice_trac 

soft_sl ice 

sp_set 

sr_sl ot 

st  ore_runner 

switch 

t_l 

t  _  2 

t_3 

task  1 


rt  s 


end  k 


alue  - 

decimal  - 

atrb. 

44 

68 

0x03 

48 

72 

0X03 

E8A 

j7ccl 

0X01 

64 

100 

0x01 

726C 

£9292 

0X01 

C 

12 

0X03 

7268 

£9288 

0X01 

7£ec 

£9324 

0X01 

7290 

29328 

0X01 

D6C 

3436 

0X01 

E7C 

3708 

0X01 

ESC 

3724 

0X01 

0 

0 

0X01 

3FF30 

£61936 

0X01 

94E 

£382 

0X01 

800 

2048 

0X01 

91C 

c!o3l~' 

0X01 

7000 

£8672 

0X01 

800 

£048 

0X01 

9E8 

£536 

0X01 

870 

£160 

0X01 

8Fft 

£298 

0X01 

0 

0 

0X03 

E90 

3728 

0X01 

E88 

3720 

0X01 

8 

8 

0X03 

3FF01 

£61889 

0X01 

4 

4 

0x03 

7000 

28672 

0X01 

704C 

28748 

0X01 

4C 

76 

0X03 

£60 

608 

0x03 

7214 

£9204 

0X01 

a 

8 

0X01 

E8E 

3726 

0X01 

7264 

29284 

0X01 

9BE 

£494 

0X01 

96A 

£4 1 0 

0X01 

3 

•  3 

0X01 

7260 

29280 

0X01 

E80 

3712 

0X01 

E86 

3718 

0X01 

976 

£422 

0X01 

E7C 

3708 

0X01 

9(42 

£466 

0X01 

9B8 

£488 

0X01 

90C 

£476 

0X01 

9D6 

£518 

0X01 

6 

6 

0X03 

91C 

C.  \j  o  l! 

0X01 

98E 

2446 

0X01 

002 

c56c' 

0X01 

B26 

£854 

0X01 

C40 

3146 

0X01 

9FC 

£556 

0X01 

(Continued  on  page  696) 


Dr.  Dobb’s  Journal,  November  1983 


45 

661 


A  DML  Parser 


How  many  times  have  you  finished 
all  but  the  user  interface  for  that 
great  new  utility  and  decided  it’s 
just  too  complicated  to  develop  a  sophis¬ 
ticated  command  processor?  Writing  a 
command  string  decoder  or  similar  utility 
from  scratch  can  be  complicated  and  may 
involve  more  effort  than  is  justified  for 
the  purpose.  Such  applications  fall  into  a 
broad  class  of  problems  relating  to  the 
parsing  of  a  source  language.  The  theory 
of  parsing  and  translation  is  well  devel¬ 
oped,  and  several  fine  tools  are  available 
that  automatically  generate  a  parser  from 
a  description  of  the  source  language.  Un¬ 
fortunately,  most  of  these  utilities  (e.g., 
the  Unix-based  YACC)  are  part  of  a  com¬ 
piler  generating  system  requiring  extensive 
support  routines  and  are  not  appropriate 
for  more  modest,  microcomputer-based 
applications. 

DML,  the  system  I  describe  in  this 
article,  is  an  attempt  to  provide  a  simple, 
yet  powerful  parsing  system  for  micro¬ 
computer  users.  Although  it  is  not  a  com¬ 
plete  compiler  generating  system,  you 
may  use  it  to  generate  the  entire  first  pass 
of  a  two-pass  compiler  for  any  well- 
formed  computer  language.  More  impor¬ 
tantly,  however,  the  parsing  phase  of  the 
system  is  designed  to  be  imbedded  in  any 
application  program  that  requires  sophisti¬ 
cated  syntax  recognition.  Once  the  syntax 
of  the  input  grammar  has  been  specified 
in  the  DML  metalanguage,  a  parsing  table 
is  automatically  generated  that  describes 
the  specified  syntactic  structures  and  di¬ 
rects  output  in  a  user-specified  fashion. 
The  parsing  table  thus  produced  is  linked 
into  the  application  program  along  with 
the  DML  runtime  code  and  voila!  instant 
parser. 

Moreover,  as  an  added  interest  to 
those  who  may  consider  exploiting  DML 
as  a  compiler  generator,  the  way  that  data 
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structures  and  semantic  operations  are 
handled  in  DML  makes  it  highly  extensi¬ 
ble.  That  is,  the  “actions”  invoked  by  the 
parser  as  well  as  the  data  structures  main¬ 
tained  may  be  altered  at  will,  and  yet  the 
syntactic  description  of  the  source  lan¬ 
guage  as  well  as  the  parsing  table  it  de¬ 
scribes  need  never  be  recompiled.  This 
gives  the  DML  system  a  Forth-like  exten¬ 
sibility. 

The  parsing  system  I  describe  is  based 
upon  a  special  purpose  metalanguage, 
modestly  called  DML.  Readers  familiar 
with  the  basic  theory  of  parsing  will 
recognize  it  as  syntactically  related  to 
Backus-Naur  Form  (BNF).  In  principle 
at  least,  if  the  syntactic  constructs  of  a 
language  can  be  described  completely  in 
DML,  the  programs  provided  will  parse 
that  language.  In  practice,  certain  limita¬ 
tions  do  exist  that  will  be  discussed  later, 
but  the  class  of  languages  that  may  be 
parsed  by  the  DML  system  is  sufficiently 
large  to  encompass  any  language  normally 
encountered;  this  includes  any  currently 
used  computer  language. 

The  DML  parsing  system  is  composed 
of  four  principal  parts:  (1)  the  semantic 
and  syntactic  constructs  of  the  DML  lan¬ 
guage  itself;  (2)  the  data  structures  that 
are  machine-executable  representations 
of  a  syntactic  description  in  DML;  and 
(3)  the  programs  that  use  such  data  struc¬ 
tures  to  parse  input  in  the  source  language. 
The  fourth  component  is  a  compiler  that 
produces  machine  representations  from 
DML  specifications.  Figure  1  (page  50) 
illustrates  the  interrelationships  between 
the  various  parts.  I  wEl  discuss  each  in 
turn. 


DML  Language  Specifications 

Perhaps  the  best  way  to  describe 
DML  is  to  present  a  simple  and  familiar 
syntax  represented  in  the  DML  meta¬ 
language.  Listing  One  (page  56)  is  a  DML 
representation  of  the  command  string 
syntax  for  the  CP/M  utility  PIP.  It  demon¬ 
strates  all  of  the  syntactic  forms  compris¬ 
ing  the  DML  metalanguage.  Later  in  the 
article.  I’ll  describe  how  to  implement  the 
accompanying  programs,  which  parse  a 
“pip”  command  string  according  to  the 
specifications  in  Listing  One. 

A  DML  syntax  specification  is  com¬ 
posed  of  a  sequence  of  productions.  Each 
production  is  composed  of  a  left  part,  or 
entry  name,  followed  by  a  followed 
by  one  or  more  syntactic  constructs,  and 
terminating  with  a  “ ;  ”.  Disregard  for  a 


moment  the  symbols  “  :  ”,  “  [  ”,  “  ]  ”, 
“ !  ”,  and  all  parenthesized  constructs. 
Two  principal  classes  of  constructs  re¬ 
main:  names  enclosed  in  angle  brackets, 
called  nonterminals,  and  single  symbols, 
possibly  enclosed  in  double  or  single 
quotes,  called  terminals.  Adjacent  sym¬ 
bols  are  related  as  in  BNF  by  an  implicit 
boolean  “and”  operator  (specified  here 
as  &).  Adjacency  implies  that  the  success¬ 
ful  recognition  of  a  preceding  construct 
must  occur  before  the  parser  can  attempt 
to  match  a  succeeding  construct.  In  the 
sequence  <ab>  dog  <ef>,  the  parser 
will  advance  to  search  for  string  “dog” 
only  if  a  match  to  nonterminal  <ab>  has 
occurred.  Similarly,  the  string  “dog” 
must  be  found  in  the  input  stream  before 
the  parser  will  advance  to  search  for  a 
match  on  nonterminal  <ef>.  An  “or” 
relationship  may  also  exist  between 
groups  of  constructs  and  is  signified  in 
DML  by  the  “  I  ”  symbol.  Conceptually, 
we  think  of  the  string  “dog”  as  a  single 
logical  entity.  In  DML,  however,  each 
character  of  a  string  is  considered  a  sepa¬ 
rate  word.  A  boolean  expression  for 
the  outcome  of  a  parse  of  <ab>  cd 
<ef>  would  therefore  be  written: 
outcome  ==  <ab>  &  c  &  d  &  <ef>. 

In  a  properly  written  DML  syntax 
specification,  each  nonterminal  appearing 
on  the  right  side  of  a  “:  =  ”construct  must 
appear  exactly  once  on  the  left  side  (as  an 
entry  name).  Note  that  terminal  symbols 
never  appear  in  a  left  part.  The  implication 
of  this  arrangement  is  that  nonterminal 
symbols  do  not  themselves  represent 
words  in  the  source  language  but  serve  as 
implicit  pointers  to  other  productions. 
Ultimately,  this  “buck-passing”  must 
terminate  in  a  production(s)  specifying 
a  sequence  of  one  or  more  words  (or  ter¬ 
minals)  in  the  source  language. 

Use  of  the  word  word  will  remain 
informal,  and  I  will  rely  on  the  reader  to 
infer  the  appropriate  meaning  from  its 
context.  It  could  denote  a  single  charac¬ 
ter  (e.g.,  ASCII  “a”)  or  a  more  complex 
collection  of  characters,  called  a  token 
(the  reserved  work  “procedure”  in  Pascal, 
for  instance).  In  this  way  the  syntax  of 
complex  sequences  of  words,  or  sen¬ 
tences,  may  be  developed  as  a  sequence 
of  smaller  constructs.  Each  production 
then  represents  a  sentential  form  in  the 
grammar  of  the  source  language.  Parsing 
an  input  is  essentially  a  process  of  identi¬ 
fying  a  correct  sequence  of  sentential 
forms.  Several  methods  can  accomplish 
this,  but  I  will  defer  discussion  of  them  to 
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the  section  devoted  to  the  parser. 

The  next  point  to  make  is  that  pro¬ 
ductions  need  not  be  defined  in  a  strictly 
hierarchical  fashion.  Although  not  dem¬ 
onstrated  in  the  simple  example  of  Listing 
One,  DML  allows  productions  to  invoke 
themselves  recursively.  Consider  two  pro¬ 
ductions  <a>  and  <b>  : 

<a>  :=  <b> ; 

<b> :=xyz |  hij  <a>; 

One  of  the  parsing  paths  in  <b>  results 
in  <a>  invoking  itself  by  indirect  recur¬ 
sion.  It  is  important  to  note,  however, 
that  neither  parsing  path  in  <b>  may 
begin  with  a  nonterminal  symbol  <a>. 
Without  this  constraint,  the  indirect  re¬ 
cursive  invocation  of  <a>  would  pro¬ 
ceed  indefinitely,  resulting  in  stack  over¬ 
flow.  The  feature  of  recursive  invocation 
allows  for  convenient  descriptions  of 
highly  complex  syntactic  structures,  but 
also  makes  it  possible  to  define  subtly 
incorrect  syntactic  descriptions.  In  prac¬ 
tice,  to  avoid  such  pitfalls,  you  need  only 
apply  a  few  simple  rules,  which  I  will 
enumerate  later.  More  advanced  compiler 
writing  systems  (e.g.,  YACC)  check  for 
constructs  that  lead  to  runaway  recur¬ 
sion;  the  DML  compiler  does  not. 

Having  given  an  impression  of  what 
nonterminals  are  and  what  they  do,  I’ll 
turn  now  to  terminal  constructs  and  the 
special  forms  they  may  have  in  DML. 
Obviously,  to  parse  an  input  in  the  source 
language,  the  parser  must  get  the  input 
words  from  somewhere.  While  you  can 
provide  the  parser  with  all  the  necessary 
facilities  to  perform  file  I/O  and  maintain 
its  own  pointers  in  the  input  stream,  it  is 
far  more  common  to  relegate  these  more 
prosaic  tasks  to  the  lexical  scanner, 
which  serves  as  an  interface  between  the 
source  and  the  parser.  DML  takes  advan¬ 
tage  of  this  arrangement  by  pushing  part 
of  the  responsibility  of  decoding  input 
onto  the  scanner,  which  can  do  it  more 
efficiently.  Consider  the  two  productions 
below: 

<character  >:=a|A|b|B|c|C... 
...x|X|y|Y|z|Z; 

<character>:=  “6”; 

The  first  specifies  that  the  parser  will 
accept  as  input  an  ASCII  character  and 
check  it  against  a  linked  list,  or  syntax 
tree,  of  valid  ASCII  alpha  characters  for  a 
match.  Since  the  syntax  tree  (described 
later)  is  rather  complex,  considerable 
computation  might  be  needed  to  perform 
this  check.  The  second  definition  of 
<character>  employs  the  special  DML 
syntactic  form  called  the  absolute  binary 
type.  This  form  (a  positive  integer  enclosed 
in  double  quotes)  requires  the  scanner  to 
check  the  input  character  against  a  pre¬ 
determined  list  of  ASCII  characters  and, 
if  a  match  is  found,  to  return  to  the  par¬ 
ser  a  type  value  of  binary  6.  Since  the 
scanner  returns  both  the  current  symbol 


and  its  type  (if  any),  the  parser  can  then 
pick  and  choose.  In  one  application,  the 
ASCII  character  may  be  needed;  in  anoth¬ 
er,  the  more  efficient  binary  type  may  be 
used.  This  construct  results  in  greater 
flexibility  and  efficiency.  Absolute  binary 
types  may  be  added  or  deleted  as  needed 
by  simple  changes  to  the  scanner  output 
routines. 

One  final  terminal  construct  remains 
undefined:  the  metaconstruct.  DML  re¬ 
quires  that  any  occurrence  of  a  metasym¬ 
bol  (a  symbol  used  in  defining  the  syntac¬ 
tic  constructs  of  DML)  outside  of  a  legal 
DML  construct  must  be  enclosed  in  single 
quotes  to  identify  it  as  a  terminal  symbol 
in  the  source  language.  This  eliminates 
ambiguities  for  the  DML  compiler. 

DML  contains  four  constructs  that 
direct  the  output  from  the  parser.  Each 
construct  represents  one  data  structure 
that  the  DML  parser  is  capable  of  generat¬ 
ing.  The  syntax  for  the  four  constructs  is 
illustrated  in  Table  I  (page  48).  (The 
actual  operation  of  the  DML-compatible 
parser  presented  in  Listing  Two  (page 
57)  must  be  partially  described  here  as 
well,  since  the  language  and  its  parser  are 
integrally  related.)  The  most  commonly 
used  data  type  is  the  semantic  stack. 
User-specified  output  to  it  is  controlled 
by  the  type  macro  —  an  integer  enclosed 
within  parentheses  preceding  the  right 
angle  bracket  of  a  nonterminal  descriptor 
(e.g.,  <abc(123)>).  This  form  causes 
the  specified  number  to  be  pushed  onto 
the  semantic  stack  on  successful  comple¬ 
tion  of  the  nonterminal.  For  example,  in 
the  production  <wildcard  name>  in  List¬ 
ing  One,  the  construct  <first  part  (15  )> 
occurs.  If  the  parser  successfully  identifies 
a  <  first  part>  construct  at  this  point  in  a 
parse,  it  is  directed  to  push  the  binary 
value  15  onto  the  semantic  stack.  This 
allows  the  specification  of  complex  con¬ 
structs  by  a  single  output  value. 

The  second  construct  available  is  out¬ 
put  to  a  symbol  table;  it  is  represented  by 
a  colon  following  the  left  angle  bracket  in 
a  nonterminal  descriptor  (e.g.,  <  :abc>  ). 
All  terminal  symbols  parsed  during  invo¬ 
cation  of  the  nonterminal  will  be  concat¬ 
enated  in  a  symbol  table  buffer.  Upon 
successful  completion  of  the  nonterminal, 
the  symbol  table  will  be  searched  for  the 
parsed  word  and,  if  it  is  not  found,  the 
word  will  be  entered.  The  symbol  table 
entry  number  is  returned  to  the  parser, 
and  a  two-number  sequence  is  pushed 
onto  the  semantic  stack.  The  first  number 
is  a  user-defined  constant  specifying 
“symbol  table  entry,”  and  the  second  is 
the  symbol  table  entry  number.  The  sym¬ 
bol  table  utility  is  not  a  formal  part  of 
the  DML  runtime  system.  The  DML  par¬ 
ser  simply  calls  an  external  subroutine 
“dgsntr”  and  expects  a  symbol  table 
number  to  be  returned.  Any  other  func¬ 
tion  desired  may  be  substituted  for  the 
symbol  table  utility  by  making  an  ap¬ 


propriate  substitution  for  the  routine 
“dgsntr.”  (The  DML  system  diskette  of¬ 
fered  to  support  this  article  contains  a 
digital  searching  symbol  table  utility.) 

The  third  construct  specifies  that  all 
correctly  parsed  terminal  symbols  be  con¬ 
catenated  into  a  string  array.  The  DML 
representation  is  similar  to  symbol  table 
output  with  the  colon  replaced  by  an 
exclamation  point:  <!abc>.  A  two- 
number  sequence  is  again  pushed  onto 
the  semantic  stack.  The  first  is  a  user- 
defined  constant  specifying  “character 
string”;  the  second  is  an  index  to  the 
string  in  the  string  array. 

To  avoid  potential  conflicts  between 
<!xxx>  and  <:xxx>  constructs,  the 
language  specification  of  DML  requires 
that  only  one  be  active  at  any  given  time; 
namely,  the  first  one  invoked.  Consider 
the  example  DML  productions  below: 

<a>  :=  <!b>  <:c>; 

<b>:  =  <:d><!e><:f>; 

While  the  !  construct  of  <b>  in  produc¬ 
tion  <a>  is  active,  output  constructs 
in  <d>,  <e>,  and  <f>  are  disabled. 
This  is  not  true  of  type  macros  like 
<xxx(123)>,  which  are  always  imple¬ 
mented  on  successful  completion  of  their 
corresponding  nonterminal. 

The  final  output  construct,  <abc 
(xyz)  >,  does  not  actually  specify  a  data 
structure;  rather  it  invokes  a  subroutine 
with  external  entry  symbol  xyz  on  suc¬ 
cessful  completion  of  the  enclosing  non¬ 
terminal.  All  such  subroutines  are  exter¬ 
nal  to  the  DML  parser,  and  there  lies  the 
secret  to  the  extensibility  of  DML  speci¬ 
fications.  These  external  routines  have 
access  to  all  stacks  and  pointers  that  the 
DML  parser  maintains  via  formal  param¬ 
eter  passing  and  global  data  specifications 
(common  blocks).  They  may  also  manipu¬ 
late  user-defined  data  structures,  perform 
semantic  processing,  or  be  modified  with 
no  effect  on  the  parser  or  its  syntax  speci¬ 
fication.  Therefore,  the  scope  of  parsing 
actions  may  be  expanded  without  chang¬ 
ing  any  part  of  the  core  DML  routines. 

DML  invokes  the  specified  external 
routines  by  calling  subroutine  “action” 
given  in  Listing  Five  (page  75).  This 
simple  routine  retrieves  the  address  of  the 
requested  routine  and  vectors  to  it  by  ap¬ 
propriately  resetting  the  program  counter. 
The  only  constraints  on  the  called  rou¬ 
tines  are:  (1)  they  adhere  to  the  parameter 
passing  conventions  of  the  DML  parser; 
and  (2)  they  appropriately  set  a  status  flag 
(“irep”)  before  returning.  The  DML 
parser  interprets  FALSE  on  return  as 
unsuccessful  completion  of  the  current 
nonterminal. 

Frequently  a  given  sequence  of  syn¬ 
tactic  constructs  repeats  one  or  more 
times  in  succession.  DML  provides  a 
mechanism  for  specifying  the  expected 
occurrence  of  such  repeats.  In  Listing 
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One,  observe  that  a  < primary  name> 
is  defined  by  the  construct  [<name 
char>  (8,1)].  The  enclosing  brackets 
imply  that  the  word(s)  specified  by  non¬ 
terminal  <name  char>  will  repeat  a 
minimum  of  once  and  a  maximum  of 
eight  times.  Since  <name  char>  may  be 
absolute  binary  type  6  (integer),  5  (a-z, 
A-Z),  or  7  (most  other  printable  charac¬ 
ters),  <  primary  name>  is  therefore  de¬ 
fined  as  an  alphanumeric  string  of  mini¬ 
mum  length  one  and  maximum  length 
eight.  Any  number  of  terminal  and  non¬ 
terminal  constructs  may  appear  within 
this  iteration  construct.  Further,  DML 
specifies  that  iteration  constructs  may  be 
indefinitely  nested,  although  adjacent 
common  left  or  right  brackets  are  forbid¬ 
den  as  shown  in  Figure  2  (page  50). 

The  absence  of  an  iteration  macro 
construct  (m,  n)  preceding  the  right  brack¬ 
et  implies  that  no  maximum  or  minimum 
iteration  count  is  required;  i.e.,  the  given 
construct  may  appear  zero  or  more  times. 
If  either  number  is  assigned  a  value  of 
zero,  the  corresponding  iteration  counter 
is  unspecified. 

The  DML  Syntax  Tree 

A  syntactic  description  in  DML,  once 
made,  must  be  translated  into  machine- 
readable  form.  This  section  describes  the 
DML  syntax  tree,  a  binary  tree  represen¬ 
tation  of  DML  syntax.  The  idea  of  using  a 
syntax  tree  graph  to  describe  syntactic 
relationships  is  not  new,  and  most  texts 
on  parsing  techniques  will  discuss  the 
basics  of  this  approach.  To  avoid  becom¬ 
ing  too  verbose,  I’ll  restrict  myself  to  its 
specific  application  to  the  DML  language. 
Henceforth,  the  words  terminal,  nonter¬ 
minal,  and  node  will  be  used  interchange¬ 
ably  since  the  binary  tree  node  ,is  the 
machine  equivalent  of  the  terminal  and 
nonterminal  syntactic  descriptors. 

At  each  step  in  the  parse,  there  are 
at  most  two  potential  pathways  to  follow. 
The  DML  language  requires  that,  if  the 
current  construct  is  matched,  a  successor, 
if  present,  should  be  tried.  If  the  current 
construct  is  not  matched,  then  an  alter¬ 
nate  (signified  by  “  |  ”  in  DML),  if  pres¬ 
ent,  should  be  tried.  The  binary  tree  is 
ideal  for  such  a  representation  since  each 
node  may  have  two  daughters,  which  we 
may  label  successor  and  alternate  in  this 
application.  If  no  other  decisions  were 
needed  at  each  node,  a  complete  syntac¬ 
tic  representation  could  be  made  using  a 
simple  binary  tree  structure.  However,  to 
fully  implement  DML,  as  many  as  ten 
decisions  must  be  made  at  each  node. 
This  results  in  a  more  complex  data  struc¬ 
ture,  but  it  is  still  essentially  a  binary  tree. 

To  implement  all  ten  decisions,  a 
total  of  sixteen  bytes  would  potentially 
be  required  at  each  node.  However,  very 
few  nodes  in  a  syntax  tree  graph  require  a 
full  sixteen  bytes,  since  most  do  not  rep¬ 


resent  the  entire  repertoire  of  DML  logical 
constructs.  In  practice,  the  average  node 
needs  only  four  or  five  bytes,  so  a  consid¬ 
erable  amount  of  space  can  be  saved  by 
including  in  each  node  only  data  elements 
that  are  necessary.  This  approach  requires 
the  addition  of  a  status  byte,  bit-mapped 
with  eight  flags.  Such  a  structure  makes 


extracting  data  elements  and  hopping 
about  from  one  node  to  the  other  a  bit 
more  complicated,  but  these  functions 
can  be  accomplished  efficiently  using  rou¬ 
tines  written  in  assembler. 

Figure  3  (below)  compares  a  DML 
syntax  specification  for  < unambiguous 
name>  from  Listing  One  with  a  graphical 


Syntax 

Action 

1. 

<abc  (nn) > 

On  successful  completion  of  <abc^> 
push  integer  nn  onto  semantic  stack 

2. 

<  !abc> 

Concatenate  all  terminal  symbols 
invoked  by  abc  into  a  string;  push 
string  location  onto  semantic  stack 

3. 

< : abc  > 

Concatenate  all  terminal  symbols 
invoked  by  abc  and  enter  into  a 
symbol  table;  push  symbol  number 
onto  semantic  stack 

4. 

<abc  (xyz)> 

On  successful  completion  of  abc, 
call  a  subroutine  named  "xyz" 

5. 

<abc  (xyz,  nn)> 

Do  1  and  4  above 

6. 

<  :abc  (xyz,  nn)  > 

Do  1,3,  and  4  above 

7. 

<!abc  (xyz,  nn)> 

Do  2,  3,  and  4  above 

Table  1 

Output  Syntax 

Scanner  - 


»- - 


-Source  language 


DML  metalanguage 
representation 


DML  compiler 


Syntax  tree  graph 
i 

-*  DML  parser 


Runtime  code 


Parser-directed 
'actions' 


_ .1... 


Standardized  output 


Figure  1 . 
DML  System 
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representation  of  a  complementary  binary 
tree  and  hypothetical  code  generated  for 
it  relative  to  a  base  address  of  1 .  The  com¬ 
plete  tree  structure  generated  for  DML 
specifications  is  rather  more  complex,  but 
I’ll  give  you  a  basic  impression  of  how 
they  work  for  this  simplified  example. 
Let  me  emphasize,  however,  that  it  is 
unnecessary  to  have  any  understanding 
whatsoever  of  how  DML  code  is  generated 
to  use  the  DML  parsing  system  effectively. 
Those  who  aren’t  interested  may  wish  to 
skip  this  section  altogether. 

Figure  3  illustrates  the  simplified  con¬ 
trol  structures  for  a  typical  production. 
Presumably  some  other  production  in¬ 
vokes  <unambiguous  name>,  causing  the 
parser  to  jump  to  the  required  node. 
Node  I  is  found  to  be  nonterminal,  so  the 
parser  again  retrieves  the  address  of  the 
requested  production  <primary  name> 
from  the  current  node  (50),  suspends 
processing  of  the  current  production,  and 
recursively  calls  itself  to  process  <pri- 
mary  name>.  On  return  from  <primary 
name>,  the  parser  pursues  a  successor 
node  if  <primary  name>  was  successful 
and  an  alternate  node  if  not.  Since  node  I 
contains  no  alternate  choice,  execution  of 
the  current  production  would  have  to 
cease  on  a  FALSE  return  from  < primary 
name>.  A  successful  return  causes  the 
parser  to  pursue  the  successor  node  lo¬ 
cated  at  6.  The  “ .  ”  found  there  is  com¬ 


pared  with  the  current  word  from  the  in¬ 
put  stream.  If  a  match  occurs,  the  input 
pointer  is  incremented  and  a  successor 
node,  if  present,  is  followed  (in  this  case, 
<extension>  located  at  11).  Note  that 
nodes  II  and  III  form  a  loop,  which  could 
be  traversed  endlessly  were  it  not  for  the 
“maximum”  specification  located  in  node 
II.  Each  time  II  is  successfully  traversed,  a 
counter  is  incremented  and  tested  against 
the  maximum  allowable  iteration  count. 
If  it  is  exceeded,  the  outcome  at  node  II 
is  set  FALSE  and  an  alternate  is  sought. 
Had  a  minimum  iteration  specification 
been  present  in  node  II,  it  would  have 
been  compared  to  the  current  iteration 


counter  when  the  alternate  path  was 
traversed,  and  an  error  would  have  been 
signaled  if  the  requisite  number  of 
iterations  had  not  been  performed. 

A  lot  of  zeros  appear  in  the  binary 
representation  in  Figure  3.  These  don’t 
exist  in  the  actual  packed  syntax  tree,  so 
the  only  way  the  parser  can  keep  track  of 
whether  a  given  node  contains  a  certain 
parameter  is  to  consult  the  corresponding 
status  bit  in  the  flag  byte  of  each  node. 
To  keep  track  of  where  the  parameter 
resides  relative  to  the  flag  byte  requires 
that  all  the  flag  bits  in  the  current  node 
be  considered.  The  parser  doesn’t  concern 
itself  too  much  with  this  arithmetic  chore; 


(a)  <f>  :=[<a>  [<bc><de>  "12"][<ef>  <gh>]  ij  (3,1)] ; 

(b)  <c>  :  =  [  [<ab>  <cd>]  ef  [<gh>  ij  <k>]  (8,1)]; 

(c)  <c>  :=  [< altl  > ef  < alt2 > (8,1)] ; 

<alt1  >  :  =  [<ab>  <cd>] ; 

<alt2>  :=  [<gh>  ij  <k>] ; 

Figure  2. 

(a)  is  a  legal  iteration  construct  while  (b)  is  not.  This  is  not  a  practical  limitation, 
since  constructs  such  as  that  shown  in  (b)  can  be  rewritten  to  eliminate  common 
adjacent  brackets,  as  shown  in  (c). 


A.  <  unambiguous  name  >:=<  primary  name  >  extension  >  (1,0)]; 


B.  ENTRY:  <  unambiguous  name  > 
l 


III 


<  primary  name  >  — 

L 

RETURN  FALSE 


<  extension  >  - 


I  (max  =  1) 

I  A 

RETURN  TRUE/FALSE 


RETURN  FALSE 


NODE 

I 

II 


ADDRESS 

1 

6 

11 


TERMINAL  (T) 
NONTERMINAL  (N/T) 

N/T  (50)* 

T 

N/T  (100)* 


INTER-NODE  POINTERS 
SUCCESSOR  (S)  ALTERNATE  (A) 

6  0 

11  0 

6  0 


ITERATION  COUNT 
MAXIMUM  MINIMUM 


0 

0 

0 


'Nonterminal  pointers:  50  =<  primary  name  >  ;  100  =<  extension  > 


Figure  3. 

Syntax -Tree  Representation 
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it’s  all  taken  care  of  by  modules  “intarg” 
and  “bytarg”  in  ddjmutls.mac,  shown  in 
Listing  Five.  Comparing  the  node  flag 
bytes  with  the  operation  of  these  two 
simple  routines  will  reveal  precisely  how 
the  parser  is  able  to  navigate  the  densely 
packed  data  types  in  a  syntax  tree  graph. 
Note  that  a  lot  of  flag  testing  gets  done  in 
the  process. 

As  previously  stated,  this  simplified 
example  is  not  the  whole  story  on  syntax 
tree  graph  structure  and  function.  Those 
wishing  to  pursue  a  more  detailed  study 
will  find  the  DML  compiler  very  helpful. 
It  has  a  trace  mode  and  logic  output  fea¬ 
ture  that,  in  essence,  traces  the  compiler’s 
“thought  processes”  in  generating  syntax 
trees. 

The  DML  Parser 

The  DML  language  specification  de¬ 
termines  what  actions  the  parser  must 
take  at  every  step  in  the  parse,  while  the 
syntax -tree  data  structure  determines 
how  the  parsing  rules  will  be  transmitted 
to  the  parser  at  runtime.  With  this  ground¬ 
work  laid,  I’ll  discuss  the  programs  that 
actually  perform  the  parse. 

Formally,  the  DML  parser  is  a  “syntax- 
tree-directed,  recursive  descent  parser,” 
one  of  a  general  class  of  parsers  called 
“top-down”  parsers.  The  mechanical 
operation  of  such  parsers  is  equivalent  to 
the  logical  development  of  DML  syntaxes: 
parsing  begins  with  larger,  generalized 
syntactic  structures  expressed  as  nonter¬ 
minals  and  proceeds  “downward”  in  a 
recursive  fashion  to  end  with  terminal 
symbols  in  the  source  language.  In  general, 
such  parsers  are  not  quite  as  efficient  as 
another  broad  class  of  parsers,  termed 
“bottom-up”  parsers.  Generating  parsing 
rules  for  bottom-up  parsers  is  more  com¬ 
plicated,  and  the  automated  systems  that 
do  so  are  not  as  easily  implemented  on 
microcomputers. 

Listing  Two  (page  57)  is  a  complete 
listing  of  the  DML  parser  in  RATFOR.  This 
may  seem  an  unlikely  choice  of  languages, 
so  I’ll  elaborate  but  make  no  apologies. 
RATFOR  source  is  far  more  readable 
than  Fortran  source  and  therefore  is  easily 
translated  into  more  widely  used  languages 
such  as  C  or  Pascal.  Furthermore,  to  spe¬ 
cify  the  invocation  of  external  actions  at 
compile  time  requires  certain  parameter 
passing  features  and  a  flexible  “.rel”  file 
format;  these  are  absent  from  the  micro¬ 
computer  implementations  of  C  with 
which  I’m  familiar  (BDS,  Small- C),  and  I 
don’t  like  Pascal.  Except  for  implement¬ 
ing  the  invocation  of  actions,  conversion 
\o  C  should  be  very  straightforward. 

Table  II  (page  53)  lists  the  array 
names  and  appropriate  pointer  variables 
corresponding  to  the  required  parser 
inputs  and  outputs  discussed  in  general 
terms  earlier.  Note  that  the  syntax-tree 
entry  point  is  also  passed  to  the  parser  as 


a  formal  parameter.  This  allows  the  same 
parser  to  use  different  syntax  trees  at 
various  points  during  program  execution. 
For  example,  in  a  compiler  application, 
the  parser  might  be  called  at  the  start  of 
execution  to  decode  the  input  command 
string,  while  later  it  would  be  used  to 
parse  the  input  source  (cdml,  the  DML 
compiler,  codes  it  that  way). 

It  is  instructive  to  note  how  recursive 
execution  is  implemented  in  a  language 
(Fortran)  that  doesn’t  normally  support 
it.  The  decision  to  use  an  auxiliary  recur¬ 
sion  stack  was  not  one  of  necessity  but  of 
choice,  since  my  runtime  memory  manag¬ 
er  allows  recursive  subroutine  calls  in 
Fortran- 80.  The  reason  has  to  do  with 
economizing  stack  space  during  the  pars¬ 
ing  of  deeply  nested,  recursive  constructs. 
Study  the  operation  of  the  recursion 
stack  and  you  will  observe  that  the  DML 
parser  saves  only  those  variables  actually 
used  at  the  particular  level  of  recursion 
(LOR)  before  descending  to  the  next.  In 
contrast,  recursive  invocation  in  Pascal 
causes  all  variables  local  to  a  procedure 
to  be  saved  and  thus  is  much  more  waste¬ 
ful  of  memory.  Additionally,  this  method 
is  bound  to  be  faster  than  a  version  using 
“pure  recursion”  on  a  Z80/8080  due  to 
the  minimal  relative  addressing  capabilities 
of  these  microprocessors. 

Earlier  I  stated  that  DML  allows  in¬ 
definite  nesting  of  iteration  constructs 
“[  )  ”.  Although  DML  may  allow  it,  the 
DML  parser  doesn’t  support  it.  The  ver¬ 
sion  in  Listing  Two  allows  a  maximum 
nesting  of  four  levels.  This  can  easily  be 
expanded  by  some  obvious  changes  to  the 
code. 

The  DML  parser  contains  another 
feature  that  greatly  facilitates  the  parsing 
of  complex  syntaxes:  it  is  capable  of  in¬ 
definite  back-up.  The  importance  of  this 
may  not  be  obvious.  Suffice  it  to  say  that, 
by  careful  specification  of  the  parsing 
rules  in  DML,  you  can  enable  the  parser 
to  examine  any  number  of  successive 
words  in  deciding  which  path  to  follow. 
The  practical  limit  of  back-up  depends 
on  the  ability  of  the  scanner  to  properly 
reset  the  input  buffers.  For  the  system 
implemented  in  the  Listings,  intended 
solely  to  parse  input  from  the  console, 
no  special  back-up  facilities  are  necessary. 
If  the  input  source  is  a  disk  file,  some 
facility  must  be  provided  to  buffer  a 
sufficient  number  of  previously  parsed 
words  to  cover  any  request  from  the 
parser  for  back-up. 

The  general  purpose  scanner  routines 
in  Listing  Four  (page  68)  may  be  used  in 
almost  any  application  to  buffer  input  to 
the  parser.  Routine  “scnint”  is  called  to 
initialize  the  scanner  at  the  start  of  execu¬ 
tion.  Each  call  to  “getsym”  causes  the 
next  valid  token  to  be  returned  from  the 
input  stream.  The  scanner  always  buffers 
enough  previously  scanned  characters  to 


allow  the  parser  to  “back  up”  at  any 
time.  If  a  back-up  is  attempted  that  ex¬ 
ceeds  the  buffering  capability  of  the 
scanner,  an  error  condition  is  signaled. 
Routine  “rstscn”  is  called  between  calls 
to  the  parser.  This  causes  the  internal 
scanner  buffer  to  be  reset  and  maintains 
the  maximum  possible  back-up  capabili¬ 
ty  at  all  times.  Changes  in  scanner  output 
(absolute  binary  types)  may  be  made 
readily  by  appropriate  modifications  to 
the  designated  block  of  code. 

Indefinite  back-up,  while  a  powerful 
tool  in  parsing  complex  structures,  does 
present  a  problem  when  you  must  inter¬ 
pret  parsing  errors.  After  error  detection, 
several  other  parsing  paths  may  be  at¬ 
tempted  before  a  global  exit  occurs.  The 
original  syntax  error  therefore  may  be 
covered  up  by  the  subsequent  abortive 
parsing  paths.  No  general  solution  to  this 
problem  exists  for  all  grammars.  DML 
deals  with  it  by  placing  one  additional 
constraint  on  all  grammars  that  are 
defined  as  parsable  by  the  system,  a 
constraint  I  term  “adamant  optimism.” 
The  frivolous  name  partly  reflects  the 
fact  that  unfortunately  no  objective 
formalisms  allow  you  to  predict  whether 
a  given  grammar  will  disobey  this  con¬ 
straint.  The  constraint  is  that  no  parsing 
path  may  be  globally  exited  successfully 
unless  the  input  symbol  pointer  is  at  a 
location  greater  than  or  equal  to  the 
maximum  value  it  has  attained  during  any 
interim  parsing  paths.  Simply  stated,  the 
parser  is  not  allowed  to  claim  a  small 
victory  if  it  has  lost  the  war. 

Study  of  the  actions  of  variables 
“backup”  and  “bakadr”  will  reveal  how 
this  is  implemented.  Error  reporting  in 
the  demo  program  in  Listing  Three  (page 
64)  “prs.rat,”  is  based  on  the  back-up 
principle.  When  a  syntax  error  is  detected, 
the  offending  character  and  up  to  nineteen 
preceding  characters  are  output  as  “con¬ 
text:”.  Following  “Current  symbol  on 
exit:”,  the  first  character  contained  in  the 
last  nonterminal  that  the  parser  attempted 
to  match  is  output.  Once  familiar  with 
this  format,  you  can  identify  not  only  the 
location  of  the  syntactic  error,  but  also 
the  larger  sentential  construct  that  was 
violated,  without  resorting  to  a  battery  of 
error  messages. 


Implementing  the  Listings 

Listing  Three  is  a  skeletal  parser- 
driver  intended  to  demonstrate  proper 
implementation  of  the  DML  system,  using 
as  a  source  grammar  the  PIP  example  in 
Listing  One.  It  demonstrates  the  proper 
method  of  initializing  variables  and  pass¬ 
ing  data  arrays  as  formal  parameters  to 
the  parser.  Since  all  array  names  are  passed 
as  formal  parameters,  you  can  allocate 
them  dynamically  if  you  have  a  suitable 
method  of  runtime  memory  management. 
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If  dynamic  memory  allocation  is  not  im¬ 
portant  in  your  application,  they  may  be 
statistically  dimensioned  as  in  Listing 
Three.  Listings  Four  and  Five  contain  all 
necessary  support  routines. 

The  RATFOR  listings  must  be  pre¬ 
compiled  and  then  compiled  using  Micro¬ 
soft’s  Fortran-80.  I  use  a  RATFOR  pre¬ 
processor  from  Aspen  Software.  With 
very  minor  modification,  the  source  code 
should  also  compile  with  the  CP/M  User’s 
Group  RATFOR  preprocessor.  The  files 
are  then  linked  according  to  the  order 
specified  in  the  leading  comments  in 
Listing  Three.  The  scanner  presented  is 
for  general  purpose  use,  including  input 
from  a  file.  In  such  applications,  the 
marked  code  in  Listing  Three  would  be 
replaced  by  a  single  call  to  “scnint”  as 
indicated,  which  takes  care  of  all  scanner 
initialization. 

The  M80-compatible  assembler  file 
“pipstx.mac”  contains  the  executable 
syntax  tree  graph  and  was  prepared  espe¬ 
cially  for  this  article  (normally  the  “.rel” 
output  from  the  DML  compiler  would  be 
linked  into  the  runtime  code).  The  addi¬ 
tion  of  external  routine  “ques”  is  meant 
to  serve  more  of  a  pedagogical  purpose 
than  anything  else.  The  syntax  specifica¬ 
tion  in  Listing  One  is  written  such  that, 
without  its  “action,”  we  would  not  know 
whether  the  “unambiguous”  file  name 
returned  was  truly  unambiguous  or  con¬ 
tained  imbedded  ?’s.  It  examines  the 
“primary  name”  and  possibly  “extension” 
found  for  the  presence  of  ?’s.  If  any  are 
found,  the  corresponding  type  declarators 
on  the  semantic  stack  are  incremented  by 
100.  This  demonstrates  a  simple  case 
where  applying  an  additional  heuristic  ex¬ 
ternal  to  the  syntax  specification  can  aid 
in  the  parsing  of  syntactic  constructs  that 
may  otherwise  be  difficult  to  express. 

Program  “prs”  prompts  with  a  “ 

Any  pip  command  line  up  to  80  charac¬ 
ters  long  of  the  form 

dev:filel.ext  = 

dev:file2.ext,dev:file3.ext, . . . 

.  . .  [OV.  .  1 

will  be  parsed.  Most  wild  card  and  abbre¬ 
viated  forms  are  supported. 

Following  a  successful  parse  of  a  com¬ 
mand  line,  the  contents  of  the  semantic 
stack  and  string  array  are  displayed.  A 
study  of  these  outputs  should  be  most 
illuminating.  Be  aware  of  one  possible 
confusion:  all  semantic  stack  outputs  are 
type  “byte”  except  string  array  indexes 
(following  the  designator  100)  and  symbol 
table  entry  number  (following  the  desig¬ 
nator  99).  These  are  type  “integer”  and 
are  displayed  by  “prs”  as  two  sequential 
bytes  in  8080-style  byte-reversed  format 
(i.e.,  512  would  be  displayed  as  00  02). 

The  syntax  as  given  contains  two 
“errors”;  that  is,  the  specified  syntax 
does  not  parse  command  lines  entirely  as 


we  might  anticipate.  I  left  them  in  because 
they  demonstrate  how  subtle  changes  in 
syntax  can  affect  the  parser.  These  two 
conditions  are,  first,  that  ambiguous  file 
specifications  of  the  form  “filename.*” 
are  interpreted  as  syntactically  incorrect, 
while  “*.ext”  and  are  parsed  cor¬ 

rectly.  The  problem  is  corrected  by  revers¬ 
ing  the  order  of  <unambiguous  name> 
and  <wild  card  name>  in  <file  specifier> 
Second,  all  option  specifiers  [ABC...] 
must  be  in  upper  case,  while  all  other 
entries  may  be  in  either  upper  or  lower 
case.  This  is  due  to  the  restrictive  defini¬ 
tions  in  <nletter>  and  <letter>. 


DOs  and  DON'Ts 

Syntax-tree  graph  representations  of 
DML  syntaxes  are  sufficiently  easy  to 
generate  and  modify  that  trial -and -error 
is  not  an  intolerable  method  of  learning. 
Still,  certain  problem  situations  should  be 
anticipated  and  thus  avoided. 

Most  difficulties  arise  from  inappro¬ 
priate  use  of  iteration  constructs  of  the 
type  [<x>’ '  <z>  ] .  Be  aware  that 
upon  detection  of  an  unmatched  symbol 
in  the  input  stream,  the  parser  resets  the 


runtime  pointers  to  the  values  saved  dur¬ 
ing  processing  of  the  most  recent  nonter¬ 
minal.  Consider  the  two  alternative  for¬ 
mulations  for  <value>  : 

<value>:  = 

[<arg><u><ments>]|  <parameter>; 

and 

<value> :  = 

[<construct>]  |  <parameter>; 

<construct>:  = 

<arg><u><ments> ; 

Assume  the  intent  in  both  cases  is 
the  same:  to  determine  whether  <value> 
is  a  series  of  “arguments”  or  a  “parameter.” 
Only  the  second  formulation  correctly 
expresses  this  intent  in  all  cases.  The 
problem  with  the  first  is  revealed  by  con¬ 
sidering  the  outcome  of  failing  to  match 
the  nonterminal  <u>.  DML  requires  that 
an  alternate  path  be  followed  on  failure. 
Since  no  alternate  path  out  of  <u>  exists 
(no  “|  ”  symbol  following  <u>),  a  glo¬ 
bal  failure  of  production  <value>  occurs 
before  <parameter>  is  tested.  In  the 
second  formulation,  global  failure  of 
<value>  does  not  occur  before  <param- 
eter>  is  tried,  regardless  of  where  an 
error  occurs  in  <construct>.  There  is 


Variable 

Name 

Description 

sb 

Symbol  buffer  —  stores  the  current  symbol  being 
parsed  in  response  to  an  active  " :  "  flag. 

ii 

Index  into  sb.  Always  points  to  the  first  free  loca¬ 
tion.  This  variable  is  local  to  parse. 

sbptr 

Saves  the  value  of  1 1  for  possible  back-up. 

ss 

Symbol  string  array  to  hold  string  output  of  the 
parser. 

jj 

Index  into  ss.  Always  points  to  first  free  location. 

ssptr 

Saves  the  value  of  jj  for  back-up. 

type 

Semantic  stack  array. 

ii 

Index  into  type.  Always  points  to  first  free  location. 

typtr 

Saves  the  value  of  ii  for  back-up. 

kk 

Index  into  the  input  source.  Always  points  to  the 
next  unmatched  character. 

ismptr 

Saves  the  value  of  kk  for  back-up. 

St 

Symbol  table  array. 

node 

Syntax  tree  graph  array. 

cndadr 

Index  into  array  "node"  of  the  currently  active 
node. 

iter 

Status  of  currently  active  iter'n  macros.  Structure: 
iter:  (1)  (2)  (3)  (4)  (5) 

# active  cndadr  max#  min#  current# 

macros  iter'ns  iter'ns  iter'ns 

Structure  (2) -(5)  repeats  a  maximum  of  three 
times  in  the  current  version. 

Table  II 

Principal  Variables  in  parse. rat 
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nothing  wrong  with  the  first  formulation 
per  se;  just  be  aware  that  the  grammatical 
rule  it  enforces  is  more  stringent.  In  con¬ 
clusion,  if  subsequent  alternates  past  an 
iteration  construct  should  be  tested,  the 
parser  must  be  able  to  unambiguously 
select  the  appropriate  parsing  path  by 
looking  at  the  first  construct  in  the  itera¬ 
tion  construct.  When  in  doubt,  reformu¬ 
late  as  in  the  second  example  above. 

Another  potential  problem  exists 
with  both  of  the  above  formulations.  Re¬ 
call  that  an  iteration  construct  containing 
no  iteration  macro  (m,n)  specifies  zero  or 
more  iterations.  Therefore,  the  first  alter¬ 
nate  will  always  match  in  both  formula¬ 
tions,  and  again  <parameter>  will  never 
be  tested.  The  solution  is  to  put  indefi¬ 
nite  iteration  constructs  last  in  a  list  of 
alternates  or  to  reformulate  them  as 
[  <construct>(0,l)] . 

Avoid  ambiguity  between  absolute 
binary  types  and  terminal  symbols  in  the 
source  language.  For  example,  if  an  abso¬ 
lute  binary  type  value  of  65  were  used, 
the  parser  could  not  distinguish  it  from 
ASCII  “A.”  The  set  of  terminal  symbols 
in  the  source  grammar  and  the  set  of  de¬ 
fined  absolute  binary  types  must  be 
disjoint. 

Finally,  do  not  use  any  left  recursive 
constructs  of  the  form: 

<a>:=  <a>bcd  |  <def>|  <gh>; 
or 

<a>:  =  <def>|  <gh>|  <a>bcd; 

The  result  is  indefinite  recursive  invoca¬ 
tion  of  <a>  until  stack  overflow  occurs. 
It  is  possible  to  show  that  such  forms  can 
be  rewritten  as 

<a>  :  =  <s>  [  bed  ]  ; 

<s>  :=  <def> |  <gh>  ; 

with  the  added  benefit  of  greater  efficien¬ 
cy  due  to  elimination  of  the  recursive 
form. 

Availability  of  the  DML  System 

The  code  provided  in  this  article  is 
sufficient  to  produce  a  working  version  of 
the  DML  parser  so  the  reader  can  explore 
its  capabilities.  To  exploit  its  full  poten¬ 
tial,  the  diskette  I  am  making  available  to 
support  this  article  is  indispensible.  The 
distribution  diskette  is  configured  for 
Z80,  CP/M  2.x.  It  contains  all  the  listings 
given  here  as  well  as  the  RATFOR  pre- 
compilations,  eliminating  the  need  for  a 
RATFOR  precompiler.  It  also  contains 
“dgsntr,”  a  symbol  table  utility  based 
upon  the  digital  searching  method;  a  com¬ 
plete  representation  of  the  DML  metalan¬ 
guage  written  in  DML;  and  “cmdl,”  the 
DML  compiler  that  produces  syntax  tree 
graphs  from  DML  specifications.  It  out¬ 
puts  code  in  Microsoft-compatible  “.rel” 
format,  machine-independent  straight 
binary,  and  a  special  trace-mode  logic 
format.  It  compiles  DML  specifications  at 
the  rate  of  approximately  60  productions 


per  minute.  Several  other  support  rou¬ 
tines  are  also  included  to  aid  in  develop¬ 
ing  and  debugging  DML  specifications. 

You  may  obtain  these  files  by  send¬ 
ing  a  stamped,  self-addressed  diskette 
mailer,  an  8-inch  diskette,  and  $5.00 
(please,  no  cardboard,  Scotch  tape,  etc.). 
Those  who  send  no  provision  for  return 
mailing  and/or  no  diskette,  send  $25.00. 
I  can  also  support  a  number  of  5Vi-inch 
formats;  write  and  inquire. 

(Listings  begin  on  page  56) 
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DML  Parser  (Text  begins  on  page  46) 

Listing  One 

’/.  pipstx.stx  -  3/15/83 

DML  representation  of  a  partial  command  syntax  for  CP/M 
version  2.2,  peripheral  interchange  until ity,  pip.com. 
For  brevity,  input  is  assumed  to  be  in  upper  case. 

A c c e p t s  c o m m a n d  1 i n e s  o f  t h e  f o rm: 

A s  F I LE 1 .  E X T=B :  F I LE2 .  EXT, C: FI LE3 .  E XT .  .  C  ATn 0 V .  .  II 

E>  u  p  p  a  r  t  s  m  o  s  t.  w  i  1  d — c  a  r  d  f  o  r  m  a  t  s . 

Y 

$  pipstx  ; 

<  command  >  ;=  [  <dev(20)>  (1,0)  I!  (file  speci f i er ( 10) )  J - 
II  <dev(20)>  (1,0)  1  (file  speci fi er ( 10) > 
l"  ’  ,  ''  II  <dev(20)>  (1,0)  11  <file  speci f  i er  ( 10)  >  3 
C  ’[’  C  <  1  option;-  (0,1)  3  'll'  (1,0)  3  ; 

(file  spec i f i er >  ; =  < unambiguous  name  (ques, 11) >  I 
<wi 1 dcard  name ( 12) >  ; 

(unambiguous  name)  ;  ~  <  .'primary  name  (13)  > 

C  .  <!  extension  ( 14)  >  (1,0)  II  ; 

(wildcard  name)  i;  :=  (first  part  (15)  >  I  (second  part  ( 16)  > 

!  (both ( 17) >  ; 


(first  part>  s  := 
( 55  e  c  o  n  d  p  a  r  t  >  ;; 


(  I  ex  t en  55  i  on  >  ;; 


p  r  1  m  a  r  y  n  a  m  e  > 


(both)- 


.  p  r  1  m  a  r  y  n  a  m  e  )  s : 


C  (name  char)  (8,1)  1 


(extension)  :=  II  (name  char)  (3,1)  II  s 


<  opt  1  on  ) 


(nletter)  C  "6"  (1,0)3  I  (letter) 


(dev)  ;=  (Idevchar)  s  5 


( devchar 


( n 1 et ter ) 

(letter)  ; 
Q  I  R 


D  !  G  !  N  I  P  I  T 


B  !  E  I  F  I  H  I  I  I  L 

S  I  U  I  V  !  W  !  Z  ; 


N  !  0  I 


(name  char)  :• 


1 1  KT  1 1  I  II  /  II  l  1 1  "7  1 1 


7.  Absolute  binary  types  d  e  f  i  n  e  d : 

"5"  ==)  a--z  or  A-Z 

11 6"  =-■=)  0  -  9 

""7"  >  all  other  print  ablets  except 

"8"  ==)  (  )  C  3 


*  n  3 


End  Listing  One 
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DML  Parser  (Listing  continued,  text  begins  on  page  46) 

Listing  Two 

#  ddjpars2»rat  —  (C)  1983,  David  J .  Harry 

#  f  o  r  n  o  n — c  o  m  m  e  r  c  i  a  1  u  s  e  o  n  1  y 

def i ne ( FALSE , «  f  al se . ) 
def i ne (TRUE, . true. ) 
def i ne ( NUL , 0) 
def i ne ( HEAP LENGTH ,17) 
def i ne ( ADDRMASK ,  z ’ 7f  f  f  ’  > 
def i ne (EXT MASK, z ’ 8000’ ) 

#  type  declarators  for  the  semantic  stack 

d e f i n e (SYM 7 Y P E , 9 9 ) # u s e r  d  e  f i n  e d 
def ine (STRINGTYPE, 100)  #user  defined 

#  s  y  n  t  a  x  t  r  e  e  n  o  d  e  f  1  a  g  v  a  3.  u  e  s 

def i ne ( ALTERNATE , 1 28) 
def i ne ( SUCCESSOR , 64 ) 
def i ne (EXCLFLAG, 32) 
d  ef i n e ( T YPFL AG ,16) 
define(MA X  F L A G , 8 ) 
define (MI NFL AG, 4) 
def  i  ne  (TERM I NAL_,  2) 
def  i  ne  ( COLON  FLAG ,  .1. ) 

#  g  3.  o  b  a  3.  f  3.  a  g  v  a  3.  u  e  s 

def  i.  n e  ( GLOB ALSTR I NG ,  32 ) 
def i ne  <  GLOBALSYMBOL , 1 ) 

#  i  t  e  r  a  t  i  o  n  c  o  n  s  t  r  u  c  t  c  o  n  s  t  a  n  t  s 

def i ne < HDRNODE , Z ’ CO ’ ) 
def i ne ( ITERCOUNT, 3) 
def  ine  (MAXC0L1NT,  1 ) 
def  i  ne  (MI. NCOUNT,  2) 
def i ne ( NUMACT I VE, 1 ) 


# ;  # 

# ;;  # 

s u b r a u t i n e  p a rse ( n o d e , s s , s t , t ype, match) 
i  m  p  1  .i  c  i  t  i  n  t  e  g  e  r  ( a  -•••  z  ) 

b y  t. e  n o d e ,  s s ,  s t ,  s b  ,  t y p e ,  d a t  a ,  m a k  v  ,  mi  n  v ,  n  t  y p  , 

max  err  ,  mi  nerr ,  syrnerr ,  ptr ,  eof  err ,  succ ,  a 3.  t. ,  ex  trn 

3.  o g  i  c a  1  max  ,  m i  n ,  m a t c h ,  p e x c  1  m ,  p c o  1  o n ,  i  r  e p ,  peof  ,  i  r  e t ,  g o u t p 

di  men  si  on  n  a  d  e  (2)  ,,  ss  (2)  ,  st  (2)  ,  type  (2)  ,  .i  ter  (2)1 )  , 
sb (25) , ptr (17) 

c  a  m  m  a  n  /  p  o  i  n  t  r  /  i  i  ,  j  j  ,  k  k ,  c  n  d  a  d  r ,  c  u  r  s  y  m ,  c  u  r  t  y  p 

#  force  sequent!  al  storage  . - . . . . — . -  > 

equivalence  (ptr  (1)  ,  pexclm)  ,,  (ptr  (2)  ,p colon)  ,  (ptr  (3)  ,  goutp)  , 
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(ptr  (4)  ,,  max 


(  p  t  r  ( 5  >  ,  m in)  ,  <  p  t  r  ( 6 )  ,ss p  t  r )  , 


# 


(  p  t  r  <  S )  ,  i  smp  t r  )  5  ( p  t  r  <  1 0 )  , 1  y p  t r )  ,,  ( p  t. r  (  12) 
(ptr  ( 14)  savsym)  ,  (ptr  ( 16)  ,  savtyp) 

-  - - >  a  s  r  e  q  u  i  r  os  d  ta  y  p  u  s  h  /  p  o  p  .. 


sbptr ) 5 


d  a  t  a  d  a  t  a ,  s  u  c:  c ,  a  1 1 m  a  x  v ,,  m  i  n  v ,,  n  t  y  p  3  e  x  t  r  n  /  0 ,,  1 , 
max  err  5  m  i  nerr  os  of  err  ,,  syonerr/20, 21 ,  22, 23/ 


#  disable  symbol  table  initialization 


i n i t “FALSE 

#  initialize  the?  1  o c a  1  b a c k u p 

bac:kup=0 

#  i  n  i  t  i  a  1  i  z  os  t  h  e  g  1  os  b  a  1  o  u  t  p  u  t 

g  o  u  t  p  ■-  FALSE 

♦^initialize  the  premature  EOF 
peof “FALSE 

#  ini  t  i  a  1  i  z  e  the  1  o  c:  a  .1  s  y  m  b  o  1 

1 1  =2 


p o i n  t  er 
f  1  ag 
f  1  ag 

b  u  f  f  e  r  p  o  i  n  t  e  r 


#  i n i t i al i z e  the  recur si  on  stac k 

i r  e  t = F A L  S E ;  call  r  p u s h ( i r  e  t , 1 ) ;  i r  e t = T  R U E 


3 


#  zero  the  iteration  construct  count 
40  i  ter  ( NUiiACT  I VE )  =0 

do  i =2, 18,4 

i ter ( i ) =0#  zero  all  node  pointers 

#  initialize  the  max  &  min  flags  for  the  current  node 
5 0  m a x  =::  ( n  o d e  ( c  n  d a d  r  )  8< M A  X  F L..  A B )  !  “FA L S E 

m  i  n  =  ( n  o  d  e  ( c  n  d  a  d  r  )  M I N  F  L  AG)  !  =  F  A  L  S  E 
if  (  ( node  ( cndadr )  &H  DR  NODE )  ==HDRN0DE ) 

■C  #  update  the  iter’n  construct  count  oars 
if  ( i t  er ( NUM ACT 1 VE ) ==0 ) 
j=2 

©1  50 


j= ( i ter (NUMACTIVE) -1 ) *4+2 
if  (iter(.j)  = c  ri  d  a  d  r ) 

og  o  t  o  1 0  0  #  c  u  r  r  e?  n  t  n  o  d  e  i  t  e  r  J  n  c  o  n  s  t  r  u  c  t  a  1  r  e?  a  d  y  a  c  t  i  v  e 
j-j+4 

• \ 

i  t  &  r  ( j  )  =»  c  n  d  a  d  r  #  a  o:  t  i  v  a  t  e  a  n  e  w  i  t  e?  r  n  c  o  n  s  t  r  u  c  t 
if  (max) 

iter ( j  + M A  X C 0 U N  T ) = b  y  t a  r  g ( n  o d  e ( c  n  d  a d  r ) n m a x  v ) 

el  se 

i ter ( j  +MAXC0UNT) =0 
i  f  ( m  i  n ) 

i  t  er  (  j  +M I NCOUNT )  =b y  t  ar  g  ( rt od e  ( c n d ad r )  ,  roi  j.  n  v ) 

el  se 

i  ter  ( .j  +M I  NCOUNT )  =0 
i ter ( j  + 1 TERCOUNT ) =0 
i  t  er  <  NUM  ACT  I  VE )  =  i  t  er  ( NUMACT I  VE )  -f  1 
.1  tt  end  if  ( — ==HDRN0DE) 

#  determine  if  current  node  is  terminal  or  non— terminal 
1 0  0  if  (  ( n  o  d  e  (cn  d  a  d  r  )  &  T  E  R  M I N  A  L )  !  -~FA  L  S  E ) 
t  #  current  node  is  TERMINAL 


(Continued  on  next  page) 
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DML  Parser  (Listing  continued,  text  begins  on  page  46) 

Listing  Two 


p  e  c:  1  m ■-  F  A  L  S  E ;  p  e  c:.>  3.  o  n = F  A  L  5  E 
c  u  i"'  d  a  t  •=  b  y  t.  a  r  g  <  n  o  d  e  <  c  n  d  a  d  r  )  d  a  t  a ) 
i f  (curdat== NU L ) 

•£#  fall  thru  a  ’null’  node 
if  < match) 

goto  300#  follow  successor  path 
el  se 

goto  500#  follow  alternate  path 

if  < !  k:urdat==curtyp  !  curdat«=cursym) ) 

r 

■_ 

match=FALSE ;;  goto  400#  further  test  unsuccessful  outcome 

match--' TRUE 
case 

■C #  p r  o c e s s  an y  a. c t  i  v e  g  1  o b a  1  f  1  a g s 
<  goutp==6L0BALSTR I NB) 

{  #  current,  char,  to  string  array 
s  s  < j  j  )  =  c  u  r  s  y  m ;;  j  j  = .  j .  j  + 1 

(goutp==GL0BALSYMB0L) 

£  #  char,  to  symbol  buffer 
sb ( 1 1 ) =cursym ;  1 1 -1 1 + 1 

•y 

c a  1 1  g e t  s y m  ( i  r e p  )  #  g e t.  n e x t  c h a r .  t o  p a rse 
if  (!  irep) 

.r 

if  (peof) 

,r 

m a t c h = F A L S E 5  c a  1 1  e r r or  ( e o f err)  ;  r e t. u r n 

J 

cursym=NUL#  give  the  scanner  one  more  chance 
curt  yp=NUL ;  peof  --TRUE 

>  #  end  if  TERMINAL 
el  se 

■i  #  current  node  is  non-TERMINAL 

#  save  ptrs.  for  possible  back-up 
typtr-’-ii  5  i  smptr=kk  5  ssptr=.jjn  sbptr=ll 
s  a  v  s  y  m c  u  r  s  y  m ;;  s  a  v  t  y  p  --  c  u.  r  t  y  p 

#  set  local  output,  flags  preserving  global  precedence 
pexcl  m-:  <  (node  (cndadr )  tkEXCLFLAB  i  goutp&6L0BALSTRINB)  !  =S> 

FALSE)  S<  (  ( g o u t p ?< G L. 0 B A L. S Y M E< 0 L )  !  =  BLDBALSYMBOL ) 

pool on= ( < node  < cndadr ) ^COLONFLAB  !  goutp&BLOBALSYMBQL )  1 

FALSE)  ?<  (  <  goutpS-:BL0BAL.  STRING)  !  =  BLOB  ALSTR I  NB ) 
if  (  (node(cndadr)  8<  TYPE  LAG)  f=  FALSE) 

{#  push  active  type  declarator  on  semantic  stack 
type  (  i  i  )  --bytarg  (node  (cndadr )  ,  rrtyp )  ;  i  i  ■”=  i  i  +1 

i  f  <  g  o  u  t.  p  =  •="  F  A  L  S  E )  #  g  1  o  b  a  1  f  I  a  g  d  i  s  a  b  1  e  s  1  o  c:  a  1  f  1  a  g  s 
f#  process  any  active  local  output  flags 
case 
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I 


(  p  c o l on ) 

f #  push  symbol  type  and  slot  for  symbol  number- 
type  ( i.  i  )  -SYMTYPE ;  i  i  — i  i  + 1 

savnum=i i ;  ii-ii+2#  save  location  for  symbol  # 

1. 

(peKCl m) 

■C  #  p  u  s  h  ’  s  t  r  i  n  g  ’  t  y  p  e  a  n  d  s  1  o  t  f  o  r  s  t  r  i.  n  g  a  d  dress 
t  ype  <  i  i  )  =STRI  NGTYF'E ;  i  i  =i  i  + 1 
s  a  v  n  u  m  =  j  j  #  i  n  d  e  x  o  f  c  u  r  r  e  n  t  s  t  r  i  n  g  b  a  s  e 
c a  1 1  i  n t. p u t  ( type  ( i  i  )  ?  j  j  )  ;  .i.  i  =» i  i  +2 ;  j  j  =  j  j +  1 

\ 

}  #  end  case 
} #  end  if(igoutp) 

tt  p  r  e p a r  e  t  o  "rec u r  s  i.  v e  1  y  "  descen d 

c  a  1 1  r  p  u.  s  h  ( p  e  x  c  1  m ,  H  E  A  F;'  L  E  N  G  T  H )  ;;  c  a  1 1  r  p  u  s  h  ( c  n  d  a  d  r ,  2 ) 

#  stack  the  iter’n  array  only  if  active 
i f  < i ter (  NUMACT I  YE)  ! -FALSE ) 

.r 

j = i  t  er  (  NUMACT  I  VE )  *  8 ;  c  a  1 1  r  p  u  sh  (iter  (2)  ,  .j ) 

#  must  save  the  1st  element  for  correct  ‘■‘pop’ 
c a  1 1  r p  u sh  (  i  t.  er  ( NUMACT  I.  VE  >  ,  2 ) 

#  set  the  global  flag  fo,  the  next  LOR 
goutp=pexcl m&EXCLFLAG  !  pcol on&COLONFLAG 

#  get  the  addr.  of  the  header  node  of  next,  production 
c  n  d  a  d  r  —  in  t  a  r  g  ( n  o  d  e  ( c  rt  d  a  d  r  )  ,  d  a  t  a ) 

tt  mask  off  any  ’external’  flags 
c  n  d  ad r  =c n d ad r  &  ADDRM ASK 

#  "call  parse" 
cal  1  rpush ( i ret , 1 ) 

Ql  Q  t  o  -4  0 

#  1 ' r e t u rn"  h e r e  f  r o m  1  o w e r  L 0 R' ’  S 
2 0 0 c a  1 1  r p o p  (  i  t e r  ( N U M A C T I V E )  ,  2) 

i f  ( i ter ( NUMACT I VE ) ! -FALSE ) 

.r 

j  =  i ter (NUMACT I VE) *3;  cal  1  rpop ( i ter (2) , j ) 

c all  rp o p ( c n d a d r , 2 ) 5  c  a 1 1  r p  o p ( p  e x c 1 m 5  H E A P L E N G T H ) 

J  #end  else  NON -TERMINAL 

#  test  for  success  of  current  and  lower  LOR’S 

if  (match) 

■C  #  match  is  TRUE 
if  (max  !  min) 

{  #  p  r  o  c  ess  c  u  r  r  e n  t  i  t  er  ’  n  c  o  n  s  t  r  u.  c  t 
.j  =*(  i  ter  ( NUMACT  I  VE )  - 1  )  *4+2 
i  ter  ( .j  + 1  TER  COUNT )  —  i  ter  (  j  + 1  TER  COUNT' )  + 1 
#  check  for  overflow  of  iter ’ n  max  count 

if  (max  &  iter ( j+ITERCOUNT) liter (j+M AX COUNT) ) 

#  set  only  one  options 


(Continued  on  next  page) 
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DEVIL  Parser 

Listing  Two 


(Listing  continued,  text  begins  on  page  46) 


c  a 1 I  e  r  r  o  r  <  m  a  k  e  r  r ) 

#  s :i.  g n a  1  a  f  a :i.  1  u re  <  f  a t a 1  e r r o r  > 
match=FALSE 

goto  450 
\ 

.>#  end  if  (max  I  min) 

#  i  n  v  o  k  e  a  c  t.  :i.  o  n  s fa  r  n  o  n — t  e  r  m  i  n  a  I  s 

i  f  (  (  (node(cndadr)  &  TERMINAL)  FALSE)  ?•: 

( .i.  n  t.  a  r  g  ( n  o  d  e  <  c:  n  d  a  d  r  )  ,,  d  a  t  a )  &  E!  X  T  M  A  S  K )  !  =  F  A  L  S  E ) 

.r 

L 

j = i  n  t  a  r  g  ( n  o  d  e  ( c  n  d  a  d  r  )  ,  e  x  t  r  n  ) 

#  a  1 1  e  r  p  a  r  a  m  e  t  e  r  p  a  s  s  i  n  g  a  s  a  p  p  r  o  p  r  i  a  t  e 

c  a  1 1  a  c  t  i  o  n  ( j  ,  j.  r  e  p  ,st5ss,type) 
if  (iirep) 

.r 

match "FALSE 

#  i  m  p  1  e  m  e  n  t  o  n  1  v  o  ne  ?  g  o  t  a J 
goto  400#  reset  continue  parse 
#goto  700  #  global  return  on  error 

!>  #  end  if (! irep) 

>#  end  if<  test  for  action. . 
if  ( g  o  u  t  p-=-- FALSE! ) 

■!!#  test  for  end  of  current  output  token 

C  3  S  E? 
r 

L 

( p  ex elm) 


•C#  terminate  the  active  string 

i=.j.j -savnudi . 1#  length  of  current  string 

ss  (savnum)  =1  #  insert,  length  at  string  base 

( p c o 1  on ) 

•[  #  t  e  r  m  i  n  a  t  e  t  h  e  a  c  t  i  v  e  s  y  m  b  o  1 

sb ( 1 ) -1 1  — 2#  length  in  symbol  buffer 
irep  TRUE  #  enable  table  entry 

#  *  *  *  call  to  external  symbol  table  utility 

#  dummied  out  for  demo  use 

#  c  a  1 1  d  g  s  n  t  r  <  s  t. ,,  s  b  i  i  n  i  t ,  i  r  e  p )  #  f  i  n  d  /  e  n  t.  e  r  c  u  r  r  e  n  t  s  y  m  b  o  1 

i  =-•  i 

#  %  >K  * 


if  (!  irep) 

•C  #  error  during  symbol  table  routine 
c  a  1 .1  e  r  r  o  r  <  s  y  m  e  r  r )  ;  i  =  0 


cal  1  intput (type (savnum) n i )  #  enter  symbol  #  in  the  semantic 
1 i =2#  reset  the  symbol  buffer  ptr« 


}  #  end  case 
...  #  end  if(igoutp) 

3001  f  (  (node  (endetdr  )  ^SUCCESSOR ) 


= SUCCESSOR ) 


s  t  a  c  k 
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C#  follow  the  successor  node 

t.  ndadr-i  ntarg  (node  (cndadr )  ,succ)  5  goto  50 

•V 

J 

else#  "return" 

.r 

goto  600 

J 

>  #  end  if (match) 
el  se 

C#  match=FALSE  —  further  test,  outcome  a.t  current  node 
400 i  f  (  (node  (cndadr  )  S<HDRN0DE>  ==HDRN0DE> 

•C#  node  is  art  iter’n  header  node 
j  = ( i ter ( NUMACT 1 OE ) - 1 ) *4+2 

if  (  !  m  i  n  !  m  i  n  ?<  .i  t  e  r  <  j  +  M I N  C  0  U  N  T )  <  —  it  er  ( .  j  +  IT  E  R  C  0  U  N  T )  ) 
m a t; c h  =  T R U E #  m i  n  a c h i  e ve d  o r  n o n e  re q u .i  r e d 

4 5 0  i t e r ( N U M A  C  T I V E ) = i t  e  r ( N U M A C T I V E ) — 1 #  d  e c  r .  cons  t r  u  c  t  c  o u  n t 

i  t. e r  ( . j )  =  0 #  z  er  a  h e a d e r  n o d e  p  t  r ,, 

>#  end  i  f  (  ■-  =- HORN  ODE; ) 

if  <kk>backup) 

•C#  update  the  backup  ptr. 
b  a  c  k  u  p  ~~  k  k  5  b  a  k  a  d  r  =  c  n  d  a  d  r 

i f  ( ( node ( cndadr ) &TERM I NAL ) ==FALSE ) 

•C#  reset  ptrs.  for  unsuccessful  non— terminal  node 
i i -typtr ;  j  j— ssptr ;  kk-i smptr 
1 l—sbptr 5  cursym^savsym;  curtyp=savtyp 

\ 

J 

5 0 0 i  f  (  ( n  o  d  e  ( c  n  d  a  d  r  )  A  L  T  E  R  N  A  T  E )  == A  L  T  E  R  N  A  T  E ) 

C #  f  o 1 1 o w  t  h  e  a  1 1 e r  n  a t e  n  o d  e  ptr. 

c  n  d  a  d  r = i  n  t  a  r  g  ( n  o  d  e  ( c:  n  d  a  d  r  )  ,  a  1 1 )  5  g  o  t  o  5  0 

}  #  end  else  (match) 

#  1 ' r e t urn"  ro u t i n e 
600  cal 1  rpop ( i ret , 1 ) 
if  (iret.) 

gotcs  200 

#  check  for  hidden  parser  failure  before?  global  return 
700  if  (backup<=kk  ?<  match) 

return 

#  report  location  of  parser  error 

match=FALSE;  kk=backup;  cndadr-bakadr 
return 

end  End  Listing  Two 


Listing  Three 


#-  prs.rat  -  3/21/83 

#  skeletal  parser  driver. 

#  loader  order  for  180s  prs,  dd  jpars2,  pi  pst>; ,  dd  jrutls,  dd  jmutl  s 


def i ne (TRUE, . true. ) 


(Continued  on  page  66) 
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DML  Parser  (Listing  continued,  text  begins  on  page  46) 

Listing  Three 


def-  i  ne  (FALSE,  .  f  al  se.  ) 
define (STACKS I ZE, 1000) 


# :  # 

#:  # 

program  prs 

implicit  integer  (a—z) 

byte  type, ss,st, buffer, dml , f cb , st  k , f cb 
logical  i rep , match , stop , eof 
external  pipstx 

d i men s i on  t  yp e ( 500 ) , ss ( 500 ) , st  <  2 ) , st  k ( ST ACKS 1 2 E ) 

common  /pointr/  i  i  ,  j  j  ,  kk ,  cndadr ,  cursym,  curtypS) 

/scan r /  f cb (36) , buffer (256) , eof , jbase, top , stop 

10  write (1,2100) 

2100  format ( '  * ' ) 

read  <1,1 000 )  ( buf  f er ( i ) , i =1 , 80) 

1 000  f  or  mat  <  80a 1 ) 

#  get  1st  valid  chr. 

#  When  input  is  via  a  disk  file,  the  blocked  code 

#  is  replaced  by  a  single  cal  1  to  ’scnint.rat’ 

#  call  scnj.  nt  <  f  1  name,  uni  t ,  i  rep ) 
tt  test  ’ i rep ’  for  TRUE  return 

stop=FALSE;  eof  =TRUE 
top=81;  kk=l;  jbase=0 
<i  1 1  i  1 1 1 1 1 1 t  1 1  ^  t 

call  getsym (match) 
if  < !  match ) 
goto  10 

call  rststk (stk, STACKSIZE)  #  reset  recursion  stack 
cndadr=l ;  i i — 1 ;  jj— 1  #  initialize  pointers 

call  parse (pipstx , ss, st , type, i rep) 
if  (irep) 

•C  #  process  successful  parse  of  input 

j=i  .i  -1 

wr i te ( 1 , 21 10)  <  type  < i ) , i =1 , j ) 

2110  f  or  mat ( ?  ’ , 1 Oi 6 ) 

if  <  j  j  ! —  1 ) 

£ 

i  =  1 

while  ( i  <  j  j ) 

£ 

m=ss(i);  itop=i+m;  i=i+l 

wr i t  e ( 1 , 2080 )  ( ss  <  k ) , k  =  i , i t op ) 

2080  format ( ’  ' , 50a 1 ) 

i =i top+1 
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y  #  end  while  (i  <  j j > 

>  tt  end  if  (j  !=  1) 

#  insert,  this  call  for  file  I/O  and  test 

#  ’ i rep ’  for  TRUE  return 
tt  call  scnrst(irep) 


>  #  end  i f  ( i rep ) 

el  se 

■C  tt  report  erroneous  production 

wr.ite(l,  2090) 

2090  formate  !  !  Syntax  error  !  !  '  ) 

j-kk-l  tt  position  of  last.  chr.  parsed 

if  ( j  <  =  0 > 
j  =  l 

m= j-20 
if  < m  <  1) 
m=  1 

wri  te  ( 1 , 2150)  cursym,  (buffer  (  i  )  ,  i  ==m,  j  ) 

2150  format!’  Current  symbol  on  exit:  ’ , la2, ’  context:  ’,25a!) 

}  tt  end  else  (irep) 

#  write  blank  lines  between  outputs 
wri  te  ( .1 , 2001 ) 

2 0 0 1  format!/) 
goto  10 

end  End  Listing  Three 

Listing  Four 

#  -  ddjrutls.rat  -  3/17/83 

def i ne ( PUSHERROR , 50 ) 
def i ne <  POP ERROR ,51) 


#:# 
tt ;  # 

subrouti ne  rpush (array, n) 
byte  irep 

cal  1  push (array, n, irep) 
i f  ( ! i rep ) 

r 

i 

c: a  1 1  er r or  ( PUSHERROR ) 
stop 

T 

J 

return 

end 


# :  tt 
tt  s  tt 

s u b  r  o u t i n  e  r  pop ( a r  r  a y , n ) 
byte  irep 

call  p  op <  ar r ay, n , irep) 
if  (  ! i rep ) 

>' 

I Continued  on  next  page ) 
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DML  Parser 


(Listing  continued,  text  begins  on  page  46) 


cal  1  error (POPERROR) 
st  op 

X 

return 

end 


#  —  scnint.rat  /  scnrst.rat  /  getsym.  rat 

#  Scan  an  input  source  file  and  return  tokens  and  token  types  to  the 

#  calling  routine.  The  buffer  always  maintains  the  previous  1.28 

#  characters  (if  possible)  to  allow  for  back-up. 

ttscnint.rat  is  called  to  initialize  the  scanner  and  read  in  the 

#  first  (two/one)  logical  sector (s) . 

# scnrst.rat  should  be  called  between  calls  to  the  parser.  In  this 

#  w  a  y t  h  e  i  n  p  u  t  b  u  f  f  e  r  p  o  i  n  t  e  r  w  i  1 1  b  e  p  r  o  p  e  r  1  y  r  e  s  e  t  a  n  d  t  h  e  m  a  x  i  m  u  m 

#  possible  back-up  capability  maintained  at  all  times. No  other  routines 

#  should  reset  the  buffer  pointer  (kk)  either  between  or  during  calls  to 

#  the  parser,  or  unpredictable  operation  may  result.  If  the  parser 

#  f  a r  c e s  a  n  i n  p  u  t  s y m b  o 1  b  a c  k  — u p  g  r  e  a  ter  t  h  a  n  t he  m  a  x i m u m  p  e r  m i s s a b 1 e 

#  value  (currently  128  total  characters,  INCLUDING  ignore  characters) , 

#  an  error  is  flagged  and  the  scanner  returns  match —FALSE. 

» 

d  ef i ne ( FALSE ,.falsa.) 
def i ne (TRUE, . true. ) 
define  < INVALID, -1 ) 
def ine (MOTHER, 9) 

#  d  e  f  i  n  e  d  s  y  m  b  o  1  t  y  p  e  s 

d  e  f  i  n  e  ( A L  P H A ,  5 )  #  u  ser  d  e  f  i  n  e d 
def i ne  < I NTEGER , 6 ) #  " 

def ine (M ISC, 7)#  " 

def ine (OTHER, 8)#" 

#  ■••••  s  c  n  i  n  t  „  r  a  t  i  n  i  t  i  a  1  i  z  e  t  h  e  s  c  a  n  n  e  r  b  u  f  f  e  r  - . .  - - . . 

#  :  tt 

#3# 

s  u  b r  o  u  t  i  n  e  s  crrr  i  n  t.  ( f  1  n  a  m  e ,  u  n  i  t ,  i  r  e  p ) 
i  m  p  1  i  c  i  t  i  n  t  e  g  e  r  ( a  -  z  ) 
b  y  t  e  b  u  f  f  e  r ,  f  c  ta 
1  o g i  c: a  1  e a f  ,  irep, s t o p 

c o  m m o n / p  o i n t  r / i i , j j , k  k , c  n  d  a d  r . c u rsym,curtyp S> 

/scanr/fcb (36) , buffer (256) , eof , jbase, top, stop 
d  a  t  a  e  o  f  e  r  r  /  2  2  / 

c a 1 1  m a  k  f  c  b ( f  c  b , f 1  name, u n i t ) 
c  all  o  p  n  f  :i  1  ( f  c  b  ,  i  r  e  p ) 
if  (i irep) 
goto  800 

cal  1  s  e  t  d  m  a  ( b  u  f  f  e  r  ( 1 )  ) 
c  a 1 1  r  d  s e q ( f  c  b , irep ) 
if  i  ! irep) 
goto  BOO 

c  a 1 1  s e t  d  m a ( b  u  f  f  e r ( 129)  ) 
c  a  1 1  r  d  s  e  q  ( f  c  b  ,  i  r  e  p  ) 
if  (iirep) 
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t  o  p  = 1 2 9 ;  eof =T R U E 
.} 

el  se 

r 

top =257 ;  eof =FALSE 

stop=FALSE 
kk=l 
j base=0 
irep=TRUE 
return 

800  call  error (eof err ) 
i rep=FALSE 
return 
end 

#—  scnrst  --  reset  input  source  to  base  of  buffer  - - — 

#:# 

#;  # 

subrout i ne  scnrst ( match ) 

.i mp licit  integer  ( a~z  ) 
byte  buffer, fcb 
1 ogi cal  eof , i rep , stop  ,  match 

common /poi ntr/i i , j  j , kk , cndadr , cursym, cur  typo) 

/scanr/fcb (36) , buffer (256) , eof , jbase, top , stop 

if  (stop) 
goto  800 

c  u  r = k  k — j  b  a  s  e 
nmove-top”Cur 

call  b 1 k m o v ( b u f f e r ( c u r),buffer(l),n m o v e ) 

t.  op=nm  o  ve+ .1.  , 

i  f  ( n  mo  ve<  =:  1 28 ) 


cal 1  setdma ( buf  f  er (top ) ) 
call  rdseq (f cb , i rep ) 
if  ( ! i rep ) 

eof =TRUE 

el  se 

top  ---top  +  128 

•v 

J 

.jbase=0 

kk=l 

match=TRUE 

return 

800  match=FALBE 

cursym= INVALID 
cur typ= INVALID 
return 
end 

get. sym „  rat  —  scan  the  input  stream 


(Continued  on  next  page) 
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DBV1L  Parser  (Listing  continued,  text  begins  on  page  46) 

Listing  Four 


# ;  # 

#  s  tt 

s  u.  b  r  o  u  t  i  n  e  g  e  t  s  y  m  <  m  a  t  c  h ) 
i  m  p  lie  i  t  :i.  n  t  e  g  e  r  < a — z  ) 
b y t e  b u  f  f  e r  ,,  f  c b ,  c u rch r  ,  m e t s y m 
1 o g i cal  e o f , m a t  c  h , ire p , stop 
d  i  m  e  n  s  i  o n  m  e  t  s  y  rn  <  NO T  H  E  R ) 

c o m m a n / p o i  ri t r / i  i  ,  .j  .j ,  k k,cnda d r ,  c u r sym ,  cur typ 3) 
/scanr/f cb (36) , buffer <256) , eof , jbase, top , stop 
data  met sym/ 60, 62,46,44,58,61 , 42, 91 , 93/ 

match— FALSE 

#  check  for  illegal  back-up  or  eof 

i f  <  k  k <  j  b a s e  !  sto p ) 
goto  800 

while  <! match) 

{#*  keep  trying  until  eof  or  legal  token  is  found 
cur- kk  --.jbase 
c  u  r  c  h  r  -  b  u  f  f  e  r  <  c  u  r ) 
k  k=kk+ 1 
cur=cur+ 1 
if  (cur  >=  top) 

•t#  test  for  end— of -buff  er 
if  < ! eof ) 

{.  #  move  buffer  down 
base=cur-128 

cal  1  bl kmov (buffer (base) , buffer  < 1 ) , 128) 
jbase-kk-129#  readjust  offset  of  buffer  base 
cal  1  setdma (buffer ( 129) ) 
cal  1  rdseq ( f  cb , i rep ) 
if  (irep) 

top =257 

el  se 

r 

K. 

top=129 
eof =TRUE 


'j-  #  end  i  f  (  !  eof  ) 
elseino  more  tokens  to  scan 

r 

L 

s  t  o  p  =  T  R IJ  E  5  g  o  t  o  8  0  0 
\ 

J#  tend  if  (cur  >=  top) 
case 

#  ***  this  section  may  be  altered  as  needed  for 

#  t. h e  p articu  1  ar  ap p  1  i  cat  i  on 
f  •#  test  for  v  a  1  i  d  token 

<curchr<33  !  curchr>126) 

;#  invalid  char,  —  ignore  it 
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(  c  u  r  c:  h  r  >  47  &  c  u  r  c  h  r  <  5  8 ) 

•f  #  INTEGER  token  found 
r  n  a  t  c  h = T  R  U  E ;  c  u  r  t  y  p  =  I N  T  E  G  E  R  5  c  u  r  s  y  m = c  u  r  c  h  r 

c ,  ( r  r  h  r  >  6  4  &  c  u  r  c:  h  r  <  9  :l.  !  c  u  r  c  h  r  >  9  6  c  u  r  c  h  r  <  1 2  2  > 

t  #  ALPHA  token  found 
m  a  t  c  h  -  T  R  U  E ;  c  u  r  t  y  p  =  A  L  P  H  A ;;  c  u  r  s  y  m  c  li  r  c  h  r 

J' 

(otherwi se) 

.r 

m  a  t.  c  I "! —  T  R  U  E ;  c  u  r  s  y  m = c  u  r  c  h  r 
do  i=l , NOTHER 

•C  #  d  e  t  e  r  m  i  n  e  t  y  p  e 

if  (cure hr  =—  metsym(i)) 

.r 

c  u  r  t  y  p = 0  T  H  E  F:! 
retur n 

>tt  end  do 
curtyp=MISC 

3-  #  end  otherwise 
>#  end  case 

#  if***# 

>  tt  end  while 
return 

8 0 0  c  u  r  s  y  m  =  I N  V  A  L.  I D 
curt yp— 1 NVAL I D 
return 
end 

#  skeletal  error  reporting  routine 
# # 

# :  # 

su.br  o  u  tine  error  (type) 
byte  type 
wri  te  ( .1.  ii  2000)  type 

2)000  format  <*  Error  !  Type  numbers  ,  1  4 ) 
return 
end 

#  ques.rat  —  simple  routine  to  demonstrate  the  use 

#  o  f  e  t  e  r  n  a  1 1  y  r  e  f  e  r  e  n  c  e  d  a  c:  t  ions « 

#  Test  for  imbedded  '  *  in  (u.n)arabiquous  filenames.  Invoked 

#  i  n  n  o  n  —term  i  n  a  1  <  u  n  a  m  b  i.  g  u  o  u  s  n  a  m  e  >  in  p  r  a  d  u  c  t.  i  o  n 

#  < file  specifier)'.  Note  ’ques’  must  ignore  1st  formal  parameter. 

def i ne  <  QUEST I ON MARK , 63 ) 
d  e  f  i  n  e  ( A  M  B I G  U  0  U  E>  i{  100) 
def i ne ( PR I MARY NAME ,13) 
define (TRUE, . true.  ) 

( Continued  on  next  page) 
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“arbcr  (Listing  continued,  text  begins  on  page  46) 

Listing  Four 


# ;  # 

#  s  # 

s u b r o u t i n e  q ues( d u m m y , i r e p , s t ,ss,ty p e ) 
i m p 1 i c it  in t e g e r  ( a — z ) 
byte  st?5S, type 
logical  irep 

d  .i.  men  s  i  on  st  <  2 )  ,ss<2)  , t  ype ( 2 ) 

c  o m m a n  /  p  o  i  n  t  r  /  i  i  ,  j  j  ,  k  k ,,  c  n  d  adr ,  c  u r  s ym ,  c  u r  t  y p 
k=i  i 

do  tot =1,2 

r 

t 

i  =  i  n  t  g  e  t  ( t  y  p  e  <  k  -•••  2 )  )  ;;  .  j  =  i  +  s  s  <  i  )  5  n = i  + 1 

do  i=n,j 

i f  ( ss < i )  ==  QUEST  I ONMARK > 

'•  <« 

type (k-4) =type<k-4) + AMBIGUOUS 
goto  100 

J 

lOOk- k-4 

i f  C  t yp  e ( k -4 )  ! =  PR I M ARYN AME ) 

goto  200 

}  #  end  do 
2 0 0  i  r  e  p = T  E  U  E 
return 
end 

#  dummy  routines  for  demo  version  —  distribution  diskette 

#  contains  all  these  routines.  Program  * prs'  is  configured 

#  such  that,  none  of  these  routines  will  be  called, 

s  u  b  r  o  !..i  t.  i  n  e  m  a  k  f  c:  b  #  C  P  /  M  f  u  n  c:  t  i  o  n  #  2  2 

return 

end 

subroutine  oprifil#  CP/M  function  #  15 

r  e  t  u  r  n 

end 

subroutine  setdma#  CP/M  function  #  26 

return 

end 

subroutine  rdseq#  CP/M  function  #  20 

return 

end 

s  u  b  r  o  u  t  i  n  e  b  1  k  m  o  v  #  b  y  t  e  o  r  .i.  e  n  t  e  d  b  1  o  c  k  ~  move  u  t.  i  1  i  t  y 
return 
end 


End  Listing  Four 
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Listing  Five 


d  d  j  m  u  1 1  s .  m  a  c  —  3  /  .1. 7  /  8  3  —  w  r  i  1. 1  e  n  f  o  r  H  i  c  r  o  s  o  f  t  ’  s  M  E?  0 


BYTARG 


I  N'T  ARC  2 


ARC ; 


AR  3.  2 


A  FT' 2 : 


equates 

DATA 

EQU 

o 

SIJCC 

EQU 

1 

ALT 

EQU 

2! 

MAX 

EQU 

M I N 

EQU 

4 

TYPE 

EQU 

5 

TORNT 

EQU 

2 

SUCCF 

EQU 

4  OH 

ALTF 

EQU 

BOH 

MAXF 

EQU 

8 

MINF 

EQU 

4 

TYPF 

EQU 

16 

TRUE 

EQU 

OFFH 

FALSE 

EQU 

o 

GLOBAL  PUSH , POP , RSTSTK , I NT ARG , BYTARG , ACT  I ON ,  I NT PUT , I NTGET 
„  Z80 


CSEG 

XOR 

A 

LD 

(RTN) , A 

JR 

ARO 

LD 

A  ^  1 

LD 

(RTN) , A 

L.D 

A, (DE) 

5  GET  FARM 

L.D 

B,  A 

LD 

C,  (HL) 

5  GET  NODE  FLAG 

INC 

HL 

;  PNT.  TO  DATA/PTR 

XOR 

A 

CP 

B 

JR 

2 , DONE 

; JUMP  IF  DATA/PTR  REQUE 

LD 

A, TORNT 

AND 

C 

JR 

NZ„ AR1 

INC 

HL 

INC 

HL 

;  HL  F'NTS  TO  SUCC 

DEC 

B 

JR 

Z , DONE 

; JUMP  IF  SUCC  REQUESTED 

LD 

A , SUCCF 

AND 

C 

JR 

Z ,  AR2 

INC 

HL 

I NC 

HL 

;  HL  PNTS  TO  ALT 

DEC  B 

(Continued  on  next  page) 
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uiviL.  parser  (Listing  continued,  text  begins  on  page  46) 

Listing  Five 


JR 

Z , DONE  ; JUMP  IF  ALT  REQUESTED 

L.D 

A , ALTF 

AND 

C 

JR 

Z ,  AR3 

INC 

HL 

INC 

HL  ;  HL  F'NTS  TO  MAX 

AR3  s 

DEC 

B 

JR 

Z , DONE  5  JUMP  IF  MAX  REQUESTED 

LD 

A, MAXF 

AND 

C 

JR 

Z ,  AR4 

INC 

HL  ;  HL  F'NTS.  TO  MIN 

AR4: 

DEC 

B 

JR 

Z , DONE  ;  JUMP  IF  MIN  REQUESTED 

.LD 

A, MINE  ;  MUST  WANT  TYPE 

AND 

C 

JR 

Z ,  AR5 

INC 

HL  ;  HL  F'NTS  TO  TYPE 

AR5s 

DEC 

B 

JR 

Z , DONE  5  JUMP  IF  TYPE  REQUESTED 

L..D 

A,  TYF'F 

AND 

C 

JR 

Z DONE 

INC 

HL. 

DONE; 

;  BET  THE  ARGUMENT 

LD 

E,  (HL) 

LD 

A,  (RTN) 

OR 

A 

JR 

Z ,,  AR6 

I NC 

HL.  ;  RETURN  AN  INTEGER 

LD 

D,  (HL) 

EX 

DE ,  HL 

RET 

AR6 ; 

5  RETURN  A  BYTE  BOTH  AS  AN  INTEGER  AND  A  BYTE 

LD 

D ,  0 

EX 

DE ,  HL.. 

L.D 

A,  L 

RET 

RTNs 

DEFB 

0 

ACT I ON ; 

5  vector  to  an  external  1 y  referenced  routine. 

LD 

A, (HL) 

INC 

HL 

LD 

H, (HL) 

LD 

L  5  A 

JP 

( H L... )  ;i  a. n d  we're  g o n e „  „  ,, 
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5ISTSTK .  MAC  /  PUSH «  MAC  /  POP.  MAC  — - - - - - 

Stack  functions  are  initialized  by  calling  RSTSTK. 

CALL  RSTSTK ( BASE ,  MBYTES ) 

BASE  points  to  a.  byte  array  of  length  MBYTES,  to  be  used  for  t! 
stack. 

P u s h  v a. r i  a. b  1  e s  o n t o  the  stack.  Check  for  s t a c k  o v erf'  1  a w  bef on 
t h e  t ransf e r .  FOR T R A M  c a 1 1  in g  for m a t  s 

CALL  PUSH ( ARRAY , MBYTES , I REP > 

Pop  variables  from  the  stack.  Check  for  stack  underflow  before 
t  h  e  t  r  a  n  s  f  e  r  „  F  0  R  T  R  A  N  c  a  1 1  i  n  g  f  o  r  m  a  t ;; 

CALL  POP ( ARRAY , MBYTES , I REP ) 


i  e 


tho 


RSTSTK 


PUSH  s 


MBYTES 

assumed 

r  0 1 u  r-  n  0 

is  the  number 
to  be  type 
d  FALSE  on  st 

of 
I  NT 

ac  k 

b  v  t  e  s  1 0  t  r  a  n  s  f  e  r  t  o 
EGER''  .  I REP  is  a  logi 
u  r>  d  e  r  /  o  v  e  r  f  1  o  w ,  T  R 

LD 

( BASE > , ML 

5  SAVE  BASE  ADDR.  OF 

LD 

(FSTFRE) „ HL 

;  I MIT.  STACK  POIMTEI 

EX 

DE,  HL 

LD 

A, (HL) 

INC 

HL 

LD 

H , (HL) 

LD 

L ,  A 

;  SAVE  STACK  SIZE 

LD 
y  np 

(STKSIZ) , HL 

ADC 

HL ,  DE 

5  CALC  ’  TOP—OF— STACK 

DEC 

HL 

LD 

(TOP)  ,HL. 

RET 

PUSH 

BC 

5  SAVE  ’ I REP’  ADDR. 

PUSH 

HL 

;  SAVE  ARRAY  ADDR. 

EX 

DE  5  HL 

LD 

E, (HL) 

;  GET  #  TO  XFER 

I NC 

HL 

LD 

D, (HL) 

PUSH 

DE 

;  SAVE  # 

LD 

HL, (FSTFRE) 

XOR 

A 

;  CLEAR  QY  FLAG 

ADC 

HL ,  DE 

DEC 

HL 

5  (FSTFRE+#-! ) 

LD 

DE, (TOP) 

SBC 

HL ,  DE 

5  (FSTFRE +#—l )  --TOP 

JR 

C ,  P 1 

POP 

HL. 

5  RE! STORE  PROGRAM  S'TT 

POP 

HL 

POP 

HL 

S  Gfc.  1  ''  Ih'tP'  ADDR . 

LD 

( HL ) , FALSE 

RE  ! 

EX  I 


(Continued  on  next  page) 
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DML  Parser 

(Listing  continued,  text  begins  on  page  46) 

Listing  Five 

P 1.  s 

POP 

BC 

3  BC  =  # 

POP 

HL. 

3  HL  =  ARRAY  ADDR. 

LD 

DE, ( FSTFRE ) 

LOIR 

LD 

(FSTFRE) , DE 

;  UPDATE  FIRST  FREE  LOCATION 

POP 

HL 

LD 

RET 

(HL) , TRUE 

POP ; 

PUSH 

BC 

PUSH 

HL 

5  SAVE  ARRAY  ADDR  „ 

EX 

DE ,  HL 

LD 

E,  (HL) 

3  GET  #  TO  XFER 

I  NO 

HL 

LD 

D,  (HL) 

PUSH 

DE 

3  SAVE  #  TO  XFER 

LD 

HL, (FSTFRE) 

XOR 

A 

SBC 

HL ,  DE 

FSTFRE  --  tt 

PUSH 

HL 

3  SAVE  POSSIBLE  NEW  FIRST  FREE  LOCATION 

LD 

DE, (BASE) 

SBC 

HL ,  DE 

JR 

NC „ PO 1 

POP 

HL 

5  RESTORE  PROGRAM  STACK  BEFORE  EXIT 

POP 

HL 

POP 

HL 

POP 

HL 

LD 

(HL) , FALSE 

RET 

PO  .1.  : 

POP 

HL 

5  HL  =  STACK  LOCATION 

POP 

BC 

;  BC  =  # 

POP 

DE 

3  DE  =  ARRAY  ADDR,. 

LD 

(FSTFRE) , HL 

;  UPDATE  FIRST  FREE  LOCATION 

LD  I R 

POP 

HL 

LD 

PF"T 

( HL ) , TRUE 

STKSIZs 

DEFW  0 

FSTF RE  s 

DEFW  0 

BASE  : 

DEFW  0 

TOP  3 

DEFW  0 

I NTPUT s 

;  su.br 

"  q  u  t.  i  n  e  t.  a  p  u  t ?  a  n  i  n  t  e  g  e  r  a  r  g  u  m  e  n  t 

LD 

A, (DE) 

LD 

( HL ) , A 

I  NC 

HL 

INC 

DE 
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!  N  T  6  E  T :  ;;  i  n  t  e  g  e  r  f  u.  n  c  t  i  o  n  t  o 

L..D  A,  (HL) 

I NC  HL 

LD  H , < HL ) 

LD  L_ ,,  A 

RET 


a n  :i.  n  t  e  g  e  r  a r  g  u men  t 


Listing  Six 


End  Listing  Five 


5  P  i  pstx  ..  mac 


assembler  version  of  pi  pstx  stx  syntax  tree 


„  zBO 

C  S  €v?  G 

cfl  oba'I  pi  pstx 
e  x  t  e  r  n  a  1  q  u  e  s 


pipst. 
clef  b 
d  e  f  b 
defb 
d  e  f  b 
( :l  e  f  b 
d  e  f  b 
d  e  f  b 
d  ef  w 
d  e  f  b 
d  e  f  b 
d  e  f  b 
defb 
def  b 
defb 
d  e  f  b 
defb 
def  b 
def  b 
d  e  f  b 
def  b 
def  b 
defb 


ODSh ,  ODBh  fl  OOh ,,  0 .1.  h  ,  OOh  3  0 Ah  ,■  OOh  ,  0 1  h  ,  .1. 4h  ?  42h  ,  OOh  ,  OEh  ,  OOh  5  50h 
6 1  h ,  OOh ,  1 4h ,  OOh OAh ,  42h ,  3Dh  ,  1 8h ,  OOh ,  ODSh ,  ODBh ,  OOh ,  1 8h ,  OOh ,  2 1  h OOh 
0 1  h  ,,  .1.  4h  ,  42h  ,  OOh  25h  ,  OOh  ,  50h  ,  6 1  h  ,  OOh ,  2Bh  ,  OOh  5  OAh  5  0C2h ,  2Ch  ,  3 :!.  h  ,  00 
44h ,  OOh ,,  ODBh  s  ODBh  H  OOh ,  3 1  h  .:i  OOh  ,  3Ah  ,  OOh  ,  0 1  h  ,,  1 4h  ,,  42h ,,  OOh ,,  3Eh ,  OOh  H  50h 
6 1  h OOh  5  2Bh ,  OOh ,  OA!  i ,  42h ,  OOh ,  48h  ,  OOh ,  OCAh ,  5Bh ,  4Fh ,  OOh ,,  5F::!"i ,  OOh ,,  0 1  h 
0E4h  ,  0C8h ,,  OOh  ,,  4Fh ,,  OOh ,  57h ,  OOh ,  01  h ,  42h ,  OOh ,  5Bh ,,  OOh ,  42h ,,  5Dh ,  48h  ,,  OOh 
02h „ OOh 5 9 Oh , 6Dh , 80h , 69h , OOh , OBh 
ques 

1  Oh ,  82h  ,  OOh ,  OCh  „  70h 0B2h 

OOh  ,,  73h  ,  OOh  *t  ODh  ,  OCAh ,  2Eh  ,  7 Ah ,  OOh ,  80h ,  OOh ,  01  h ,  70h  ,  OBDh  ,  OOh ,  73h  ,  OOh 
OEh 02 h ,,  OOh ,  90h ,  92h ,  OOh  ,,  88h ,  OOh  ,,  OFh ,  90h ,,  9Dh ,  OOh ,  8Eh ,  OOh  ,,  1  Oh  ,  .1.  Oh 
0A8h  ,  OOh  ,r  1  Ih ,  42h ,  2Ah ,  96h ,  OOh ,  42h  5  2Eh  ,  9Ah ,  OOh ,  20h  ,  OBDh  ,  OOh  ,  60h  ,  0B2h 
OOh  ?  0A6h OOh ,  42h  ,  2Eh ,  0A6h  s  OOh  02h 2Ah 42h  ,  2Ah ,,  OACh ,  OOh ,  42h 2Eh ,,  OBOh 
OOh  <i  02h ,  2 Ah ,  OCCh  ,  30h ,  0 1  h  ,  0B2h ,  OOh ,  OBBh ,  OOh «  08h ,  0 1  h ,  02h ,  OOh  ,  OCCh »  30h 
0 1  ti ,  OBDh  ,,  OOh  ,  0C6h ,  OOh  ,,  03 h  ,  0 1  h  ,,  02h ,  OOh  ,,  OCOh ,,  0E4h ,,  OOh  ,  OCFh  ,,  OOh  ,,  ODBh  ,,  OOh 
OCAh 5  06 h , OCFh , OOh , 0D6h , OOh , 0 1 h , 02h , OOh , OOh , 0F6h , OOh , OOh , 0E2h »  OOh , OEOh 
OOh ,  02h ,  3 Ah ,,  02h ,  05h ,  S2h ,  44h ,  0E8h ,  OOh ,  82h ,  47h ,  OECh ,  OOh  ,,  82h  ,  4Eh  ,  OFOh 


OOh , 82h 
4. Oh ,  02h 
4 Eh, 12h 
53h , 22h 
5 Ah ,  82!  "i 


„  501 1 , 0F4h  ,  OOh »  02h  ,  54h ,  82h  ,  42h  5  OF  Ah  ,,  OOh ,  82h  ,  45h  ,  OF  Eh  „  OOh  ,  82h 
,,  0 1  h ,  82h ,  48h ,  06h ,  0 1  h  ,  82h ,  49h  ,,  OAh ,  0 1  h ,  82h ,,  4Ch  ,  OEh  ,,  0 1  h ,  82h 
,  0 1  h ,  82h ,  4Fh ,  1 6h  ,  0 1  h  ,  82h  ,  5  3.  !"i ,  1  Ah ,  0 1  h  ,  82h ,  52 h  ,  1  Eh ,  0 1  h  ,  82h 
5  0 1 h , 82h , 55h , 26h , 0 1 h , 82h „ 56h , 2Ah , 0 1 h , 82h „ 57h , 2Eh , 0 1 h , 02h 
,  05h 3 34 h 3  0 1 h , 82h , OOh , 38h , 0 1 h „ 02h , 07h 


End  Listing  Six 
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Towards  a  More  Writeable 
Forth  Syntax* 


While  Forth  is  a  powerful  and 
efficient  language,  it  may  also 
be  justly  criticized  for  creating 
unnecessary  programmer  obstacles.  Par¬ 
ticularly  objectionable  are  the  stack 
operators  which  tend  to  obscure  the  orig¬ 
inal  solution,  increase  programmer  error, 
and  result  in  code  which  is  often  virtually 
unreadable. 

We  will  describe  a  set  of  Forth  exten¬ 
sions  designed  to  reduce  programming 
effort.  These  extensions  provide  the  fol¬ 
lowing  features: 

(1)  A  programming  style  that  requires  no 
explicit  parameter  stack  operations, 

(2)  A  straightforward  notation  for  defin¬ 
ing  recursive  functions, 

(3)  The  handling  of  forward  references, 
and  » 

(4)  A  new  construct  for  defining  higher 
order  functions  that  is  similar  to 
CREATE  DOES>  but  easier  to  use. 

The  principal  goal  in  designing  a  pro¬ 
gramming  language  should  be  to  reduce 
the  effort  required  to  translate  a  problem 
solution  into  a  machine  language.  Our 
specific  goal  with  the  extensions  to  Forth 
has  been  to  preserve  the  power  and  flexi¬ 
bility  of  the  language  while  providing  a 
simpler  and  more  readable  notation.  The 
resulting  code  is  not  unlike  a  postfix  dia¬ 
lect  of  Pascal  or  Algol.  We  will  discuss  the 
syntax  of  the  extensions  and  their  imple¬ 
mentations. 

Forth  programmers  tend  to  be  impa¬ 
tient  with  attacks  on  the  syntax  of  the 
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language,  since  the  advantages  of  Forth 
seem  clearly  to  outweigh  any  minor  in¬ 
conveniences.  Yet  Forth  does  have  short¬ 
comings,  as  some  critics  have  repeatedly 
pointed  out.1’2  The  most  common  com¬ 
plaint  is  the  lack  of  readability.  We  will 
demonstrate  extensions  to  the  language 
which  provide  a  “better”  syntax,  one 
which  is  entirely  free  of  stack  operations. 
By  “better”  we  mean  both  more  writable 
and  more  readable. 

An  Example  With  Recursion 

Consider  this  example  of  the  Acker- 
mann  function  described  by  Peterson.3 
The  function  ack(i,  j)  is  recursive  and  is 
given  by 

j+  1  if  i  =  0 

ack(i  -1,1)  if  j  =  0 

ack  (j  -1 ,  (  ack  (i,  j  -  1 ) )  otherwise. 

In  Forth  the  function  ack  is  defined  re¬ 
cursively  as  shown  in  Figure  1  (page  82). 
The  definition  is  perhaps  not  unreadable, 
but  neither  is  it  clearly  related  to  the 
original  formulation.  Suppose  we  restate 
the  original  function  definition  in  reverse 
Polish : 

if  I  =  0  J  1  + 

if  J  =  0  I  1  -  1  ACK 

otherwise  J  1  -  I  J  1  -  ACK  ACK. 

With  the  extensions,  the  Forth  colon  def¬ 
inition  is  rewritten  with  a  new  notation 
where  the  parameters  i  and  j  are  declared. 
The  resulting  program  definition  is  very 
close  to  the  problem  definition  —  in  re¬ 
verse  Polish.  Note  that  the  words  <  DE¬ 
FINE  and  »  in  Figure  2  (page  82)  play 
the  roles  of  :  and  ,  respectively. 

Notice  that  the  new  programming 
definition  is  virtually  identical  to  the  re¬ 
stated  function  definition.  We  suggest 
that  the  new  syntax  is  not  only  more 
readable  but  is  more  writable.  For  this 
example  and  similar  problems,  the  nota¬ 
tion  greatly  reduces  the  time  to  resolve 
programming  errors.  Our  goal  is  simply  a 
syntax  which  relates  directly  to  the  state¬ 
ment  of  the  solution.  This  makes  the  pro¬ 
grammer’s  job  a  great  deal  easier.  We  can 
go  even  further  in  providing  a  more  reada¬ 
ble  definition.  If  we  create  a  new  vocabu¬ 
lary  within  which  (  (left  parenthesis),  ) 
(right  parenthesis),  and  ,  (comma)  are 
redefined  as  immediate  no-operations, 
the  definitions  of  ACK  may  be  rewritten 
as  demonstrated  in  Figure  3  (page  82). 

In  a  later  section  we  sketch  imple¬ 
mentation  of  the  extensions.  Note  that: 

(a)  The  new  definitions  may  be  mixed 


freely  with  Forth  colon  definitions, 
(b)  Declared  variables  (I  and  J  above) 
can  be  referenced  only  inside  the 
definition.  They  occupy  no  perma¬ 
nent  dictionary  space. 

A  Simple  Example 

The  new  approach  is  useful  for  non¬ 
recursive  functions  as  well.  Consider  the 
comparatively  simple  problem  of  calculat¬ 
ing  the  value  a  *c  -  b/c  given  the  values  of 
a,  b,  and  c.  The  Forth  glossary  entry  is 

VAL  ABC - A*C  -  B/C 

In  Forth  we  write 

:  VAL  ROT  OVER  *  ROT  ROT  /  -  ; 

We  suggest  that  the  relationship  between 
the  expression  A  *  C  -  B/  C  and  the  ex¬ 
pression  ROT  OVER  *  ROT  ROT  /  - 
is  not  obvious.  It  is  possible,  however,  to 
make  the  programmer’s  job  easier,  reduce 
the  chances  of  error,  and  provide  a  more 
readable  definition. 

The  expression  A  *C-B/Cis  writ¬ 
ten  in  reverse  Polish  as 

(a)  A  C  *  B  C  /  - 

The  corresponding  definition  in  the  new 
notation  is 

<  DECLARE  VAR  A  VAR  B  VAR  C 

<  DEFINE  VAL 

(b)  (  returns  )AC*BC/-  >> 

Note  that  the  expressions  (a)  and  (b) 
above  are  identical.  We  merely  rewrite 
our  solution  as  our  programming  defini¬ 
tion. 

Implementation  and  Efficiency 

The  extensions  require  that  a  stack 
called  the  lambda  stack  be  added  to  the 
Forth  system.  Values  corresponding  to 
the  declared  variables  are  removed  from 
the  parameter  stack  at  execution  and 
pushed  onto  the  lambda  stack.  A  declared 
variable  used  in  a  definition  will  retrieve 
the  corresponding  value  from  the  lambda 
stack  at  execution  and  push  it  onto  the 
parameter  stack. 

The  names  of  declared  variables  are 
allocated  space  in  a  portion  of  the  dic¬ 
tionary  available  only  during  compilation. 
This  space  is  reused  for  subsequent  defini¬ 
tions  so  that  declared  variables  require  no 
permanent  dictionary  space. 

Preliminary  experiments  with  the  ex¬ 
tensions  indicate  marginal  increases  in 
execution  time  of  20  to  30  percent  and 
even  less  impact  upon  memory  require¬ 
ments.  On  the  other  hand,  programmer 
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time  for  coding  and  debugging  will  typi¬ 
cally  be  halved. 

Temporary  Values 

The  extensions  include  a  feature  that 
handles  intermediate  or  temporary  values. 
It  eases  the  bookkeeping  burden  of  a 
Forth  programmer  who  must  otherwise 
keep  cuff  records  of  values  on  the  param¬ 
eter  stack  and  the  return  stack.  Suppose 
we  extend  the  computation  of  the  previ¬ 
ous  example.  We  compute  the  value 

NEWVAL 

ABC - (A*C-B/C)2+(A*C-B/C)-C2 

Since  we  need  to  compute  the  value  of 
A*C-B/C  only  once,  we  introduce  the 
idea  of  a  temporary  value  and  rewrite  the 
expression  in  reverse  Polish  as 

A  C  *  B  C  /  -  TEMP  LET 

(  i.e.  :  let  temp=  [a*c-b/c]  ) 

and  then  calculate 

TEMP  TEMP  *  TEMP  +  C  C  *  - 

In  Forth  NEWVAL  is  defined  as 
shown  in  Figure  4  (page  82).  The  stack 
operations  are  only  distantly  related  to 
the  original  problem.  Contrast  this  with 
the  example  in  Figure  5  (page  83).  The 
word  LOCAL  defines  temporary  storage 
local  to  the  new  definition.  No  permanent 
dictionary  storage  is  needed  for  the  name 
TEMP. 

Forward  References 

One  of  Forth’s  structural  require¬ 
ments  is  that  all  words  must  be  defined 
before  they  are  used.  While  this  is  not 
generally  a  problem,  it  can  be  constrain¬ 
ing.  Often  we  rewrite  a  definition,  use  a 
word  not  yet  defined,  and  then  discover 
that  correcting  the  difficulty  requires  a 
messy  reordering  of  the  load  sequence. 

The  word  FORWARD  relieves  the 
problem  in  a  simple  way.  To  use  a  word 
not  yet  defined  we  write 

FORWARD  <  name  of  new  word  > 

The  word  FORWARD  builds  a  definition 
which  looks  like 

:  <  name  of  new  word  > 

ERROR-ROUTINE  ; 

where  execution  of  ERROR-ROUTINE 
displays  an  error  message.  Later  in  the 
load,  a  definition  of  the  form 

<  DECLARE  .  .  .  <  DEFINE 

<  name  of  new  word  >.  .  .  >> 

replaces  the  address  of  ERROR-ROUTINE 
in  the  colon  definition  created  by  FOR¬ 
WARD  with  the  address  of  the  new  word. 

The  process  is  simple,  and  the  syntax 
convenient. 

A  New  High  Level 
Defining  Construct 

The  CREATE  DOES>  facility  in 
Forth  allows  the  definition  of  words 


which  are  themselves  defining  words.4- s 
CREATE  DOES>  is  a  powerful  capabil¬ 
ity  found  in  few  computer  programming 
languages,  but  because  the  construct  is 
not  simple  to  use,  it  is  often  avoided  by 
less  experienced  programmers.  We  will 
describe  a  syntax  for  the  definition  of 
defining  words  which  provides  a  capa¬ 
bility  similar  to  CREATE  DOES>  but 
with  a  simpler  notation.  Consider  the 
Forth  definition  of  the  defining  word 
MATRIX. 

MATRIX,  given  the  parameters  M 
and  N,  allocates  an  M  *  N  byte  array  and 
defines  a  new  word  which  requires  the 
parameters  I  and  J.  The  new  word,  when 
executed,  insures  that  I  and  J  are  in  the 
range 

1  <  I  <  M  and  1  <  J  <  N 
If  they  are  not,  an  error  message  is  dis¬ 
played.  Otherwise  the  location  of  the  I, 
Jth  byte  in  the  array  is  returned. 

The  definition  of  MATRIX  in  Forth 
is  shown  in  Figure  6  (page  83).  Contrast 
this  with  (he  new  definition  in  Figure  7 
(page  83): 

Note  that  in  this  definition,  the  word 
CALLOCATE  reserves  bytes  (ALLO¬ 
CATE  reserves  words).  The  word 
ADDRESS  will  return  the  address  of 
the  first  reserved  location.  Also  note 
that  the  location  of  the  I,  Jth  ele¬ 
ment  is  given  by 

ADDRESS  +  N  *(I-1 )+(  J-l ) 
which  in  reverse  Polish  is 
ADDRESS  N  I  1  -  *  +  J  1  -  + 

The  new  definition  is  displayed  in  Figure 
7  (page  83). 

Summary 

While  technology,  each  year,  provides 
more  powerful  hardware  at  less  cost,  our 
software  problems  seem  to  defy  solution. 
Forth  provides  unique  capabilities,  but  if 
Forth  is  to  be  accepted  by  large  numbers 
of  programmers  it  will  be  because  Forth 
makes  programming  easier.  Our  goal  in 
developing  the  extensions  has  been  to  add 
to  Forth’s  capability  by  providing  a  nota¬ 
tion  that  more  directly  relates  a  program¬ 
ming  solution  to  the  original  problem.  We 
feel  that  the  extensions  are  a  step  towards 
this  goal.  The  impact  upon  machine  ef¬ 
ficiency  is  marginal  while  programmer 
productivity  is  considerably  enhanced. 
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FIG.  1 
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FIG.  3 
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J  1 
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I  1 

-  ,  1  )  ACK 
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THEN 
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J  1  -  ,  (  I  ,  J  1  -  )  ACK  ) 

ACK 
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>> 

FIGURE  4 


NEWVAL  (  a  b  C 
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DUP  DUP  *  ( 

+  ( 

R>  DUP  *  -  ;  ( 


-  [a*c-b*c]**2  + 

save  c  ) 
a*c  ) 
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temp  =  [a*c-b/c]  ) 
temp*temp  ) 
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temp* temp+temp-c*c 


[a*c-b/c]  -  c**2  ) 


FIGURE  5 


< DECLARE  VAR  A  VAR  B  VAR  C  LOCAL  TEMP 
< DEFINE  NEWVAL 

A  C  *  B  C  /  -  TEMP  LET  (  set  temp  to  a*c-b/c  ) 
(  returns  )  TEMP  TEMP  *  TEMP  +  C  C  *  -  >> 
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FIGURE  6 
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FIGURE  7 

<  DECLARE 

VAR  M  VAR  N 
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parameters  for  the  defining  word  ) 

DECLARE 

VAR  I  VAR  J 

( 

parameters  for  the  new  word  ) 

<  DEFINER 

MATRIX 

( 

definition  time  action  ) 

M  N  *  CALLOCATE 

( 

reserve  m*n  bytes  ) 
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I  1  <  J  1  <  OR 
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this  is  what  the  word  does  ) 

(  test  i  <  1  and  j  <  1  ) 

I  M  >  J  N  >  OR 

OR 

(  test  i  >  m  and  j  >  n  ) 

I  F 

ELSE 
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II 

(  bounds  error  if  they  are  ) 
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ADDRESS  N  I  1  -  *  +  J 
THEN  >>> 

1  - 

+  (  ADDRESS  +  n* [ i-1]  +[j-l]  ) 
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Simple  Graphics  for  Printer 


Marek  W.  Michalski,  in  “A  Simple 
Vector  Generation  Algorithm” 
( DDJ  No.  74,  December  1982,  pp. 
58f),  reinvents  (almost)  the  classic  algo¬ 
rithm  for  plotting  straight  lines.  This  was 
independently  discovered  about  20  years 


by  Wil  Baden 


Wil  Baden,  339  Princeton  Drive,  Costa 
Mesa,  California  92626. 


ago  by  a  number  of  people,  and  was 
published  as  “Algorithm  for  Computer 
Control  of  Digital  Plotter,”  written  by 
J.  E.  Bresenham  in  the  IBM  System  Jour¬ 
nal,  4(1)  1965,  pp.  25-30. 

The  algorithm  is,  of  course,  intended 
to  be  implemented  in  machine  language, 
and  the  arithmetic  calculations  are  mini¬ 
mal  -  using  just  addition,  subtraction,  and 
perhaps  left  shift  (to  multiply  by  2).  It  is 
important  to  avoid  using  time-consuming 
multiplication  and  division.  Also,  the 


actual  inner  loop  is  very  simple. 

Anyone  who  is  interested  in  algo¬ 
rithms  or  graphics  should  know  about  the 
Bresenham  algorithm.  It  not  only  does 
the  job,  it  does  it  well.  The  Michalski 
algorithm  requires  more  computation, 
does  not  always  make  the  best  choice  for 
its  first  move,  and  plots  two  points  when 
it  should  plot  only  one  in  the  degenera¬ 
tive  case  of  zero  distance. 

A  Pascal  program  is  provided  which 
uses  the  Bresenham  algorithm  for  very 
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Figure  1. 

Flowchart  diagrams  depicting  the  inner  loops  of  the  Bresenham  and  Michalski  algorithms. 
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low  resolution  graphics  on  your  terminal 
or  line  printer  (though  the  algorithm  can 
also  be  the  basis  for  much  higher  resolu¬ 
tion  graphics  routines).  Procedures  are 
provided  for  move  absolute,  move  relative, 
line  absolute,  line  relative,  draw  lozenges 
and  oblongs,  and  for  drawing  flowcharts 
of  the  inner  loop  of  the  Bresenham  and 


Michalski  algorithms. 

The  Pascal  code  (see  Listing,  below)  is 
in  standard  Pascal,  and  should  thus  work 
on  most  Pascal  compilers.  The  letters  in 
the  flowchart  boxes  in  Figure  1  (page  86) 
may  be  found  in  the  comments  of  the 
Pascal  listing  (page  89,  lines  87-111).  As 
the  flowcharts  illustrate,  the  Bresenham 


algorithm  has  the  simpler  structure.  ••  j 

( Listing  begins  below ) 


Simple  Graphics 

Listing 

1  program  plotting  (input* output)  >  -C  simple  graphics  for  printer  > 


2 

const 

3 

XMAX  =  80  ; 

■c 

horizontal  rasters  > 

4 

YMAX  =  88  » 

■c 

vertical  rasters  > 

5 

MAXSAYE  ^  20  5 

■c 

stack  size  > 

6 

type 

7 

xraster  =  l.*XMAX  J 

8 

yr aster  =  l.*YMAX  J 

V 

var 

•c 

global  variables  > 

10 

pixel  1  arrayExraster* yraster 3  of  char  i 

■c 

the  graphic  window  } 

11 

x  1  xr aster  i 

■c 

current  position  > 

12 

y  t  yraster  » 

13 

s  t  1 * .MAXSAVF  * 

-c 

stack  pointer  } 

14 

xsave  1  array! 1. .MAX8AYE1  of  xraster  J 

-c 

stack  > 

15 

ysave  5  array! 1. .MAXSAYE3  of  yraster  i 

16 

function  sgn  (x  5  integer)  1  integer  5 

■c 

signum  of  x  > 

17 

begin 

18 

if  (x  <  0)  then  sgn  *.=  -1 

19 

else  if  (x  =  0)  then  sgn  1=  0 

20 

else  -Cx  >  0}  sgn  «=  1 

21 

end  » 

22 

function  abs  <x  !  integer)  5  integer  > 

■c 

absolute  value  of  x  > 

23 

begin 

24 

if  (x  <  0)  then  abs  1=  -x 

25 

else  abs  I-  x 

26 

end  > 

27 

procedure  mads  (xl  J  xraster  >  yl  t  yraster  )  » 

-c 

move  absolute  > 

28 

begin  <  beware  —  lacks  range  check  > 

2V 

x  t=  xl  » 

30 

y  yl 

31 

end  > 

32 

procedure  nr el  (dx  t  integer  i  dy  1  integer  )  » 

-c 

move  relative  > 

33 

begin 

34 

mabs  (x+dx*  y+dy) 

35 

end  » 

36 

procedure  setup  > 

■c 

initiation  > 

37 

var  xl  1  xraster  »  yl  1  yraster  » 

38 

begin 

39 

for  yl  J=  1  to  YMAX  do 

40 

for  xl  !=  1  to  XMAX  do 

*11 

pixel! xl*  yl]  t=  '  '  * 

42 

x  :=  i  ; 

(Continued  on  next  page) 
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Simple  Graphics  (Listing  continued,  text  begins  on  page  86) 

Listing 


13  y  :=  i  ; 

s  *■-  o 

15  end  > 

16  procedure  cleanup  >  -C  termination  > 

17  var  ;<1  ♦  xr aster  >  yl  «  yr  aster  > 

■18  begin 

19  writeln  » 

50  for  yl  5=  1  to  YMAX  do  begin 


51 

for  :<1  :=  1  to  XMAX  do 

5? 

write(pixelL'xlryll)  i 

53 

writeln  J 

51 

end 

55 

end  i 

56 

procedure  fork  > 

{  save 

current  position  ' 

57 

begin 

-C  beware  —  lacks  overflow  check  > 

58 

5  ♦=  5  +  1  > 

59 

xsavetsD  *=  x  J 

60 

ysaveCs]  1=  y 

61 

end  » 

62 

procedure  back  5 

-C  revert  to  old  position 

63 

begin 

-C  beware  —  lacks  underflow  check  > 

61 

nabs  (xsaveCsUr  ysaveCs 3) 

t 

65 

s  l-  s  -1 

66 

end  i 

67 

procedure  cabs  <xl  1  xr aster 

>  yl  t  yr aster  5  marker  2  char)  * 

68 

begin 

69 

mabs  (xl>  yl>  J 

70 

pixelCx»y3  1=  marker 

71 

end  ♦ 

7? 

procedure  labs  <xf  «  xr aster 

»  yf  ♦  yraster)  t  -C  line 

absolute  > 

73 

var  sxr  sy  «  -1..1  » 

-C  increment  to  next  pixel 

> 

71 

dxr  dy  t  integer  » 

-t  projection  of  vector  on 

axes  > 

75 

f  <  integer  » 

■C  direction  finder  > 

76 

begin 

77 

cabs  <x»y»'*')  i 

78 

dy  1=  abs(yf-y)  » 

i  vertical  movement  > 

79 

sy  1=  sgn(yf-y)  i 

<.  vertical  direction  > 

80 

dx  :=  abs(xf-x)  i 

-C  horizontal  movement  > 

81 

sx  5=  sgn(xf-x)  » 

-C  horizontal  direction  > 

82 

if  (dx  <  dy)  then  begin 

83 

•C  Bresenham  algorithm  for  prolate  motion  > 

81 

dx  t=  2  *  dx  > 

■C  short  adjustment  > 

85 

f  J=  dx  -  dy  ; 

•C  initial  direction  > 

86 

dy  :=  f  -  dy  i 

-C  long  adjustment  > 

87 

while  (y  <>  yf)  do  begin 

■C  P  > 

88 

y  !=  y  +  sy  ! 

■C  move  on  long  axis  > 

-C  A  > 

89 

if  (f  <  0)  then 

■i  Q  > 

90 

f  :=  f  +  dx 

<  add  short  distance  > 

t  B  > 

91 

else  begin 

92 

X  1=  X  +  sx  * 

-C  move  on  diagonal  > 

<  C  > 

93 

f  :=  f  +  dy 

•C  add  adjustment  > 

{D> 

91 

end  » 

88 
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95 

cabs  (x»  y»  '*') 

-t  next  point  > 

•C 

E  > 

96 

end 

97 

end 

98 

else  tdx  >=  dyl  begin 

99 

■C  Bresenham  algorithm  for  oblate  motion  > 

100 

dy  :=  2  *  dy  » 

■{  short  adjustment  > 

101 

f  {=  dy  -  dx  J 

-C  initial  direction  } 

102 

dx  1=  f  -  dx  t 

•C  long  adjustment  > 

103 

while  (x  <>  xf)  do  begin 

■C 

P  > 

104 

x  :=  x  +  sx  ; 

■C  move  on  long  axis  > 

■C 

A  > 

105 

if  (f  <  0)  then 

-C 

Q  > 

106 

f  }=  f  +  dy 

-C  add  short  distance  > 

< 

B  > 

107 

else  begin 

108 

y  <=  y  +  sy 

»  -C  move  on  diagonal  > 

< 

C  > 

109 

f  J=  f  +  dx 

■i  add  adjustment  > 

< 

D  )• 

110 

end  ? 

111 

cabs  (x»  yr  '#') 

-C  next  point  > 

< 

E  > 

112 

end 

113 

end 

114 

end  t 

115 

procedure  lrel  (dx  t  integer 

1  dy  1  integer)!  <  line 

relative  > 

116 

begin 

117 

labs  (x+dxr  y+dy) 

*118 

end  J 

119 

procedure  diamond  (marker  1 

char)  t  <  draw 

a  lo 

zenge 

120 

begin 

•C  enter  at  top  > 

121 

labs  (x»  y+1)  i 

122 

labs  (x+3»y+2)  > 

123 

labs  (x-3»y+2)  » 

124 

labs  (x-3»y-2)  J 

125 

labs  (x+3>y-2)  > 

126 

cabs  (x>  y+2»  marker)  » 

127 

mabs  (x»  y+2)  J 

128 

labs  (x»  y+1) 

129 

end* 

130  procedure  box  (marker  t  char)  »  {  draw  an  oblong  > 

131  begin  <.  enter  at  top  > 

132  labs  (x»  y+1)  i 

133  labs  (x+4>y)  5 

134  labs  (x>  y+4)  i 

135  labs  ( x-8 » y )  i 

136  labs  <x>  y-4)  i 

137  labs  (x+4»y)  > 

138  cabs  (xi  y+2»  marker)  > 

139  mabs  (x»  y+2)  > 

HO  labs  ( x »  y+1) 

HI  end  \ 

H2  procedure  bresenham  »  -C  Bresenham  algorithm  > 

H3  begin 

144  fork  J  mrel  (4>3)  i  lrel  (6>0)  > 

145  lrel  <0r-2)  >  lrel  (5»2)  i  lrel  (-5r2)  5  lrel  (0»-2)  1  back  J 

H6  diamondCF")  5  box('A')  i 

147  fork  5  mrel  (4r3>  i  Lrel  (6.0)  1  lrel  (0  »3)  ;  box('C')  J 

(Continued  on  next  page) 
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Simple  Graphics  (Listing  continued,  text  begins  on  page  86) 

Listing 


148  box('D')  ;  lrel  (0»3)  i  lrel  (-10,0)  i  back  » 

149  diamond ( 'Q1 )  *  box('B’)  *  lrel  (0*12)  ;  box('E')  5 

150  lrel  <0,  3)  i  lrel  (-10*0)  *  lrel  <0*-42)  »  lrel  (6*0)  * 

151  end  * 

152  procedure  michalski  •  -C  Michalski  algorithm  > 

153  begin 

154  box('E')  ;  box ( ' A ' )  i  boxt'B')  } 

155  fork.  »  mrel  (4*3)  *  lrel  (6*0)  5  lrel  (0f3)  * 

156  fork  >  diamond ( 'R‘ )  *  lrel  < 0 » 15)  ►  back  * 

157  mrel  (4»3)  *  lrel  (6*0)  *  lrel  (0*3)  * 

158  box('C')  ;  box('D')  »  lrel  (0*3)  *  lrel  <-20»0>  i  back  > 

159  diamond ( ' Q ' )  >  lrel  (0*24)  *  diamond ( * P* )  * 

160  fork  *  mrel  (-4*-3)  *  lrel  (-6*0)  *  lrel  (0*-48)  »  lrel  (6*0)  }  back  * 

161  lrel  (0*1)  *  lrel  (-3*0)  ♦  lrel(3*3)  *  lrel(3*-3)  *  lrel(-3*0)  * 

162  end  * 

163  begin  -C  main  > 

164  setup  *  mabs  (11*1)  »  bresenham  *  mabs  (51*1)  *  michalski  *  cleanup  * 

1 65  end  . 


End  Listing 


(Continued  from  page  661) 


task_l_sp 

B20 

£848 

0X01 

t  ask__£ 

B20 

£848 

0X01 

task_£_sp 

C44 

3140 

0X01 

t  ask_3 

C44 

3140 

0X01 

task_3_sp 

D6C 

3436 

0X01 

tenth_ constant 

C350 

50000 

0X01 

trap_0 

80 

1£8 

0X01 

user _sr_ mask 

0 

0 

0X01 

wait 

958 

£39£ 

0X0.1. 

was_5uper 

9D4 

£516 

0X01 

End  Listing 
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SOFTWARE  REVIEWS 


WP6502  VI. 3a 

Company:  Dwo  Quong  Fok  Lok  Sow, 

548  Broadway,  Suite  4F,  New  York, 

NY  10012 

Computer:  M/A-COM  OSI  (Ohio  Scienti¬ 
fic),  versions  OS65U  and  OS65D 
Price:  $300.00  for  V.OS65U  and  $250.00 

for  V.OS65D 

Circle  Reader  Service  No.  125 
Reviewed  by  James  Criscione 

Those  of  us  who  actively  use  OSI  sys¬ 
tems  in  our  everyday  lives  constantly 
envy  our  associates  who  have  products 
such  as  WordStar,  which  perform  their 
word  processing  functions.  Over  the  past 
several  years,  OSI  has  turned  out  a  num¬ 
ber  of  word  processors  (the  WP-X  series) 
that  are  simply  redoings  and  patchings  of 
their  early  editor/assembler.  This  has  left 
the  OSI  user  in  a  wasteland  into  which 
WP6502  by  DQFLS  fits  in  sufficiently. 

As  word  processors  go,  it  would  best 
be  described  as  “middle  of  the  road.”  It 
is  very  good  at  handling  text  for  inser¬ 
tions,  deletions,  additions,  and  displaying 
this  in  a  variety  of  proportional /right 
justified  modes,  depending  on  the  type  of 
printer.  True  proportional  spacing  can  be 
accomplished  only  on  parallel  printers. 
Serial  printers  use  either  micropropor¬ 
tional  spacing  (varying  the  spacing  be¬ 
tween  words  in  small  increments)  or  a 
simple  justification  mode  based  on  whole 
space  increments  between  words  depend¬ 
ing  on  the  capabilities  of  the  printer. 

The  WP6502  system  is  menu-driven 
so  that  it  is  very  easy  for  the  novice  user 
to  begin  word  processing.  The  system  is 
booted  and  an  Install?  message  is  dis¬ 
played.  This  gives  the  user  the  opportuni¬ 
ty  to  reconfigure  the  system  to  the  type 
of  CRT  and  printer  currently  in  use.  It  is 
only  necessary  to  do  this  one  time  for 
each  system  as  these  parameters  are  saved 
to  disk. 

If  the  install  option  is  not  selected, 
the  menu  displays:  Type,  View,  Blk  view, 
G.Edit,  L.Edit,  Move,  Delete,  Zap,  Send, 
Receive,  and  Clerk.  Type  is  the  mode  se¬ 
lected  to  input  text  to  the  word  processor. 
Text  is  displayed  as  entered,  and  it  is  not 
necessary  to  enter  “RETURN”  at  the 
end  of  the  line  because  the  system  does 
this  automatically.  View  is  selected  if  the 
operator  wishes  to  see  the  display  of  text 
either  on  the  CRT  or  the  printer.  The  sys¬ 
tem  also  allows  “Blocks”  of  text  that 
may  be  predefined  and  inserted  at  any 
point  in  work  in  progress  simply  by  enter¬ 
ing  #Bnn  where  nn  is  the  block  of  text  to 


select.  This  is  useful  in  form  letters,  or  as 
a  boilerplate  for  legal  documents.  One 
drawback  is  that  the  text  must  be  con¬ 
tained  in  memory,  so  you  are  limited  to 
the  size  of  the  blocks  that  may  be  ac¬ 
cessed  at  any  one  time. 

The  system  also  allows  for  both  glo¬ 
bal  and  line  edits  in  a  fairly  standard 
fashion.  Text  may  also  be  moved  from 
one  location  to  another,  and  the  user  has 
the  option  of  either  retaining  the  existing 
text  and  the  moved  text  or  having  the 
system  automatically  delete  the  old  text. 
The  delete  command  is  useful  for  deleting 
large  blocks  of  text  although  most  text 
will  probably  be  deleted  in  the  line  edit 
mode.  Zap  is  to  clear  the  memory  prior 
to  entering  text. 

The  Send  and  Receive  options  are 
supposed  to  allow  the  user  to  transfer 
text  from  one  system  to  another  via  com¬ 
mon  printer  ports.  This  portion  does  not 
work  as  specified  and  we  have  not  been 
able  to  get  adequate  explanation  from 
DQFLS  despite  numerous  calls,  most  of 
which  went  unreturned.  I  suspect  from 
the  method  in  which  the  few  calls  were 
returned  that  DQFLS  is  a  part  time  soft¬ 
ware  house  and  the  programmers  have 
other  employment;  for  in  no  case  was 
anyone  ever  available  directly  who  could 
answer  any  questions  regarding  the  soft¬ 
ware. 

The  CLERK  command  on  the  menu 
allows  the  user  to  manipulate  the  actual 
disk  files  (save,  load,  create  new  files,  etc.). 
This  is  an  improvement  on  DQFLS’s  prior 
offerings  in  which  this  had  to  be  done 
outside  of  the  menu. 

In  summary,  WP6502  is  an  adequate 
word  processing  system  for  OSI  mini’s.  It 
does  not  have  many  of  the  features  that  a 
more  sophisticated  system  might  offer, 
but,  for  the  simple  manipulation  of  text, 
does  reasonably  well.  The  programs  seem 
to  run  fairly  well  so  I  think  the  difficulty 
with  software  support  will  not  be  really 
crucial. 


DATA  CAPTURE/pc 

Company:  Southeastern  Software,  7743 
Briarwood  Drive,  New  Orleans,  LA 
70128 

Computer:  IBM  PC  with  128K  Memory 
Price:  $120 

Circle  Reader  Service  No.  127 

Reviewed  by  Chuck  Crayne 

DATA  CAPTURE/pc  is  a  terminal 
emulation  program  that  supports  the 


asynchronous  adapter  card  for  the  IBM 
personal  computer.  Like  the  other  com¬ 
munications  packages  on  the  market,  this 
program  will  allow  the  IBM  PC  user  to 
communicate  with  host  computers,  public 
access  data  networks,  and  other  personal 
computers.  The  unique  feature  of  this 
particular  program  is  that  it  contains  a 
text  buffer  that  can  capture  about  750 
lines  of  40  characters.  When  buffer  cap¬ 
ture  is  in  effect,  all  input  and  outpu  are 
stored  into  the  buffer  at  the  same  time 
that  they  appear  on  the  screen. 

When  I  was  a  HAM  TTY  operator,  it 
was  considered  good  form  to  pre-type 
(on  paper  tape)  outgoing  messages  before 
going  on  the  air.  This  practice  not  only 
saved  a  lot  of  time  for  the  other  operators 
on  the  net,  but  avoided  exposing  my  own 
fumble-fingered  typing  skills  to  the  world. 
On  today’s  computer  nets,  an  additional 
factor  applies  —  the  connect  charge. 

The  capture  buffer  makes  the  process 
of  pre- formatting  messages  a  lot  easier 
than  using  punched  paper  tape.  After  the 
program  is  initialized,  but  before  it’s 
logged  onto  the  net,  you  can  type  your 
messages  onto  the  screen.  They  will  be 
captured  in  the  buffer.  Then,  when  you 
are  signed  into  the  right  section  of  the 
net,  you  can  easily  cause  any  or  all  of  the 
messages  to  be  sent. 

A  similar  function  could  be  done 
with  programs  that  support  file  uploads, 
but  it  would  require  that  the  files  be  pre¬ 
viously  created  with  some  sort  of  text 
editor.  Even  then,  to  match  the  versatil¬ 
ity  of  DATA  CAPTURE,  each  message 
would  have  to  be  in  a  separate  file. 

If  the  capture  buffer  overflows,  it 
will  automatically  be  written  to  disk. 
Alternatively,  the  user  can  choose  to  cap¬ 
ture  directly  to  disk,  send  from  disk,  or 
do  file  maintenance  functions,  all  without 
leaving  the  communications  environment. 

The  capture  buffer  has  a  price,  how¬ 
ever.  The  current  version  of  the  program 
requires  a  128K  system.  Without  the  buf¬ 
fer,  it  could  either  run  on  a  smaller  sys¬ 
tem  or  contain  additional  features.  There 
is  no  dialing  directory,  for  example.  Nor 
is  there  any  provision  (such  as  the  XMO¬ 
DEM  protocol)  for  transferring  non-text 
files. 

The  functions  that  do  exist,  however, 
are  easy  to  use.  The  beginner  or  occasional 
user  will  be  pleased  with  the  menu-driven 
approach  to  reaching  the  desired  function. 
The  expert  user  can  bypass  the  menu  and 
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reach  any  function  directly  from  the 
communication  screen.  The  documenta¬ 
tion  is  above  average,  containing  both  an 
indexed  reference  manual  and  a  17-page 
tutorial. 

The  current  version  of  DATA  CAP- 
TURE/pc  is  DOS  2.0  compatible.  South¬ 
eastern  Software  will  upgrade  previous 
versions  for  $5.00  with  return  of  the  orig¬ 
inal  master  diskette.  Any  diskette  whose 
serial  number  starts  with  the  letter  “B”  is 
the  DOS  2.0  version.  Serial  numbers  start¬ 
ing  with  “A,”  or  no  letter  at  all,  should 
get  the  new  version  if  they  plan  to  use 
DOS  2.0. 

DATA  CAPTURE/pc  gets  good  marks 
for  documentation  and  ease  of  use.  All 
data  communications  packages  for  the 
IBM  PC  must,  however,  be  compared  to 
Andrew  Fluegelman’s  PC -TALK  III.  PC- 
TALK  has  become  extremely  popular  due 
to  the  FREEWARE  approach  in  which 
each  user  of  the  program  is  encouraged  to 
give  away  copies.  The  recipient  of  each 
copy  is  encouraged,  but  not  required,  to 
send  $35  to  the  program  author. 

To  compete  against  this  approach,  a 
program  selling  at  $120  must  offer  some¬ 
thing  of  significant  value  that  is  not 
available  in  PC-TALK.  The  unique  feature 
that  DATA  CAPTURE/pc  offers  is  the 
capture  buffer.  If  you  are  paying  signifi¬ 
cant  amounts  in  access  charges  for  300  or 
1200  baud  communications  while  you 
type  at  30  or  less,  this  program  could  be 
a  good  investment. 

/HELP 

Company:  Southeastern  Software,  7743 
Briarwood  Drive,  New  Orleans,  LA 
70128 

Computer:  IBM  PC  with  one  drive  and 
128K,  or  COMPAQ  with  one  drive 
and  192K 
Price:  $39.50 

Circle  Reader  Service  No.  129 
Reviewed  by  Diane  Crayne 

Every  beginning  BASIC  programmer 
needs  /HELP!  This  is  one  of  the  nicest 
little  programming  aids  to  come  along  in 
quite  a  while.  In  fact,  it  is  so  nice  and 
simple  that  I  wonder  why  someone  didn’t 
think  of  it  a  long  time  ago. 

/HELP  is  a  memory  resident  program 
that  you  can  call  up  to  give  you  a  short 
description  of  practically  any  BASIC 
command.  And  you  can  do  this  right  in 
the  middle  of  coding  a  program,  without 
losing  track  of  where  you  are,  or  inter¬ 
fering  with  what  you’re  doing.  You  car 
also  use  /HELP  to  describe  the  most 
common  DOS  commands. 

This  nifty  little  memory  aid  runs  on 
the  IBM  PC  and  the  COMPAQ.  Its  only 
drawback  is  the  memory  requirement  of 
42K;  it  needs  128K  to  run  on  the  PC,  and 
192K  on  the  COMPAQ.  Unfortunately, 
this  puts  it  beyond  the  reach  of  the  peo¬ 


ple  who  will  probably  have  the  most  need 
for  it  —  the  beginning  programmers  who 
may  have  a  64K  system. 

I  tested  /HELP  on  a  128K  IBM  PC 
with  two  dual  drives.  The  only  documen¬ 
tation  I  had  was  the  little  nine-page 
booklet  that  comes  with  the  software. 
That  was  all  I  needed.  Installation  is  a 
true  snap.  Format  the  disk  you’re  going 
to  use  for  your  next  BASIC  program  and 
put  it  in  drive  B:.  Put  the  /HELP  disk  in 
drive  A:.  Log  on  to  drive  A:.  Type  MAKE 
I  if  you’re  using  a  PC,  and  MAKE  C  if 
you’re  using  a  COMPAQ.  /HELP  copies 
onto  the  target  disk  and  installs  itself  into 
memory  when  you  log  onto  B:  and  type 
HELP.  That’s  all  there  is  to  it.  The  book¬ 
let  also  has  installation  instructions  for 
people  with  single-drive  systems. 

Once  /HELP  is  installed,  all  you  have 
to  do  is  type  /  and  a  friendly  little  mes¬ 
sage  appears  at  the  top  of  the  screen: 
“What  would  you  like  /HELP  with?” 
You  can  either  press  the  enter  key  and  go 
back  to  whatever  you  were  doing  (/HELP 
blanks  the  top  ten  lines  of  the  screen  for 
its  messages),  type  ?  to  see  a  list  of  the 
commands  you  can  get  help  with,  or  type 
in  the  name  of  a  command  and  get  a 
quick  refresher  on  how  it  works. 

Naturally  the  descriptions  aren’t 
exhaustive  —  you  can  only  do  so  much 
in  ten  lines  —  but  they  show  one  or  two 
examples  and  that’s  usually  enough  to 
remind  you  about  the  syntax.  If  what 
you’re  doing  is  too  arcane  for  /HELP  to 
cover,  you  can  always  refer  to  the  proper 
page  in  the  IBM  PC  BASIC  manual,  which 
is  neatly  printed  in  brackets  at  the  top 
right  of  the  /HELP  area. 

If  you  don’t  like  using  the  /  key  to 
invoke  /HELP,  you  can  change  the  call 
character  to  anything  you  want.  All  you 
have  to  do  is  hit  the  slash  key  a  second 
time  when  the  prompt  appears,  and  you’ll 
be  prompted  for  a  new  character.  The 
manual  suggests  that  you  use  a  printable 
character  and  not  a  control  or  funtion 
key.  Being  of  a  contrary  nature,  I  selected 
the  FI  function  key.  /HELP  seemed  to 
run  fine,  but  the  prompt  line  didn’t  com¬ 
pletely  display  on  the  screen.  So,  I  bowed 
to  the  wiser  heads  behind  the  product 
and  chose  the  =  key  instead. 

I  had  a  particular  reason  for  picking 
=  as  the  call  character.  It  is  one  of  the 
most  frequently  used  characters  in  BASIC 
programming.  I  wanted  to  know  if  it 
would  mess  up  either  /HELP  or  my  pro¬ 
gram;  it  didn’t.  You  can’t  call  /HELP  if 
you  have  entered  a  line  number  and  are 
in  the  middle  of  editing  a  BASIC  state¬ 
ment.  Once  the  command  description  has 
been  displayed,  you  can  type  the  access 
character  again  and  request  another 
description.  This  eliminates  having  to 
toggle  back  and  forth  between  the  pro¬ 
gram  screen  and  the  /HELP  screen  when 


you  have  more  than  one  query. 

/HELP  can  be  a  very  useful  tool  for 
the  beginning  programmer.  Its  descrip¬ 
tions  are  concise;  its  examples  are  easy  to 
understand;  and  its  $39.50  price  tag  is 
quite  attractive.  It’s  a  tool  with  a  limited 
life-span  (since  the  programmers  will 
outgrow  it);  but  for  the  time  it’s  being 
used,  it  will  save  hours  of  frustrated 
searching  through  the  manual. 

Displaying  the  BASIC  manual  page 
numbers  is  a  nice  feature,  but  the  num¬ 
bers  only  match  version  2.0.  If  you  have 
an  earlier  version,  or  if  IBM  releases  a 
newer  one,  the  numbers  will  be  out  of 
synch. 

/HELP’S  main  problem  is  the  128K 
memory  requirement.  There  are  evidently 
a  few  quirks  lurking  in  the  bushes  too, 
since  the  manual  advises  against  having 
/HELP  in  memory  when  you’re  running 
other  programs.  The  results,  they  say, 
“can  be  unpredictable.”  When  you  use 
the  program  the  way  it’s  intended,  the 
results  are  quite  predictable  —  and  very 
good ! 

SuperWriter 

Company:  Sorcim  Corporation,  2310 

Lundy  Avenue,  San  Jose,  CA  94131 
Computer:  IBM  PC 
Price:  $295 

Circle  Reader  Service  No.  131 
Reviewed  by  Ronald  G.  Parsons 

I  have  used  many  word  processors 
during  the  past  six  or  seven  years  —  some 
on  large  mainframes,  some  I’ve  written 
myself,  some  stand-alone  units,  and  some 
on  personal  computers.  SuperWriter  beats 
them  all  in  one  very  important  category 
—  ease  in  learning  to  use  it.  Just  a  few 
hours  after  receiving  this  copy  for  review, 

I  had  converted  a  large  document  from 
WordStar  and  was  modifying  it  with 
SuperWriter. 

It  is  only  natural  (and  reasonable)  to 
compare  a  personal  computer  word  proc¬ 
essor  to  WordStar  as  it  is  one  of  the  cur¬ 
rent  best  sellers.  My  main  experience  with 
WordStar  is  with  their  CP/M  version  using 
a  memory-mapped  video  board,  but  that 
version  performed  better  than  the  versions 
I’ve  used  on  the  IBM  PC  (I  understand 
the  new  version  of  WordStar  for  the  IBM 
PC  does  correct  some  of  the  extreme 
slowness  of  screen  updates). 

SuperWriter  has  the  capabilities  of 
WordStar  and  its  MailMerge  and  SpellStar 
companions  in  one  package  at  about  a 
third  of  the  suggested  retail  price.  I  found 
no  significant  function  available  from 
WordStar  and  similar  packages  that  was 
not  present  in  SuperWriter.  The  excellent 
help  screen  facility  available  in  SuperWrit¬ 
er  and  the  speed  of  screen  updates  make 
the  package  a  very  good  value. 

I  have  had  three  occasions  to  call 
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Sorcim’s  customer  service  department 
with  questions  on  SuperCalc  and  Super- 
Writer  and  the  response  has  always  been 
swift  and  accurate  (even  one  day  when 
their  phones  were  out  of  order  and  they 
called  me  back).  Micropro,  on  the  other 
hand,  took  over  six  months  to  respond  to 
a  problem  with  SpellStar  and,  after  re¬ 
peated  calls  and  letters  from  me,  finally 
responded  that  nothing  could  be  done  — 
“that’s  the  way  it  is.”  Sorcim’s  manuals 
are  clear,  easy  to  use,  and  professionaly 
done.  Micropro’s  on  the  other  hand.  .  . 
(I’ve  heard  their  new  ones  have  finally 
been  redone).  1  found  that  I  needed  to 
use  only  the  SuperWriter  reference  card 
and  the  help  screens  with  occasional 
references  to  the  index. 

This  is  not  to  say  that  SuperWriter 
does  not  have  its  faults.  Like  WordStar, 
there  is  no  “undo”  command  to  reverse 
an  erroneous  deletion.  Keys  on  the  IBM 
PC’s  keyboard,  such  as  PgUp,  PgDn,  and 
End  are  not  used  for  their  labeled  func¬ 
tions  (I’ll  describe  a  cure  for  this  problem 
using  PCDOS  2.0  a  little  later).  The  print¬ 
er  1  use  has  a  2000-character  buffer  and 
the  printer  driver  times-out  waiting  for 
the  buffer  to  empty. 

One. of  my  favorite  features  of  Word¬ 
Star  is  absent  —  page  breaks  in  SuperWrit¬ 
er  are  not  visible  on  the  screen  while  you 
are  editing.  Provision  is  available  to  pre¬ 
vent  widows  and  orphans  (those  single 
lines  at  the  beginning  and  end  of  para¬ 
graphs  that  end  up  respectively  on  the 
bottoms  and  tops  of  pages)  but  I  like  to 
be  able  to  see  where  the  page  ends. 

I  like  several  features  on  SuperWriter 
much  better  than  on  WordStar.  In  Super- 
Writer,  for  example,  as  a  paragraph  is 
modified,  the  line  ends  are  readjusted  in 
real  time  rather  than  waiting  for  the  user 
to  request  reforming  of  the  paragraph. 
When  the  cursor  is  moved  vertically  in 
WordStar,  it  jumps  to  the  left  if  it  passes 
a  short  or  zero  length  line. The  SuperWrit¬ 
er  cursor  stays  in  a  single  column.  The 
visible  indications  for  bold  and  underline 
are  much  more  mnemonic  than  the  cryptic 
control  symbols  on  WordStar.  I  get  the 
feeling  that  I  am  using  three  separate 
packages  when  using  WordStar/MailMerge/ 
SpellStar,  whereas  the  SuperWriter  fea¬ 
tures  are  integrated  much  better  as  a  single 
package. 

The  form  letter  generation  capabili¬ 
ties  are  very  similar.  However,  SuperWriter 
has  the  capability  of  reading  fixed-format 
data  files.  The  procedural  capabilities  with 
IF  logic  are  quite  good.  The  SuperWriter 
spelling  checker  is  much  faster  than  Spell- 
Star.  On  two  identical  files  of  around 
3400  words,  SpellStar  took  127  seconds 
to  complete  the  check  while  SuperWriter 
took  only  23  seconds.  SpellStar  was  run¬ 
ning  with  diskettes  while  SuperWriter  was 
on  a  fixed  disk  on  a  PC  XT,  which  could 
explain  some  of  the  difference,  but  I’m 
sure  that  much  of  the  time  difference  is 


real.  Each  package  has  a  20,000+  word 
dictionary.  The  SuperWriter  spelling 
checker  flagged  105  “words”  while  Spell¬ 
Star  flagged  88.  Both  dictionaries  are  weak 
on  plurals  and  words  with  suffixes  and 
prefixes.  SpellStar  often  flags  words  with 
apostrophes  while  SuperWriter  flagged 
many  with  hyphens. 

SuperWriter  lets  you  review  the  mis¬ 
matched  word  list  so  the  “correct”  words 
can  be  eliminated  before  marking  them  in 
the  text.  This  is  very  useful  in  long  docu¬ 
ments  with  a  large  amount  of  jargon. 
Adding  words  to  the  SuperWriter  diction¬ 
ary  is  very  easy  to  do.  SpellStar,  on  the 
other  hand,  marks  all  or  none  of  its  flagged 
words  in  the  body  of  the  text.  Words  in 
this  review  that  were  flagged  by  the  two 
spelling  checkers  (eliminating  proper 
nouns,  abbreviations,  etc.)  are  listed 
below: 

Flagged  by  both:  configures  cure  direc¬ 
tives  mainframes  menus  mnemonic 
nouns  orphans  overridden  overrides 
phones  plurals  redefines  redefinition 
redefinitions  redone  reentered  re¬ 
forming  sellers  widows 
SuperWriter  flagged  readjusted  verifica¬ 
tion  (plus  most  hyphenated  words) 
SpellStar  that’s  author’s  mismatched 
Sorcim  Micropro  ASCII 

Isn’t  it  interesting  that  SpellStar  marked 
Sorcim  and  Micropro  as  misspelled,  but 
SuperWriter  marked  neither! 

A  Typical  Session 

The  system  is  organized  around  a  ser¬ 
ies  of  full  screen  menus.  The  main  menu 
presents  a  choice  of  EDITing  a  document, 
QUITing  to  the  operating  system,  PRINT- 
ing  a  document,  CHECKing  spelling  in  a 
document,  getting  a  list  of  the  DISK 
directory,  or  executing  a  set  of  provided 
UTILITIES.  Choosing  EDIT  (the  default 
choice  —  others  are  made  by  moving  the 
cursor  with  the  space  bar  and  pressing 
enter)  causes  a  filename  to  be  requested. 
If  it  is  to  be  a  new  file,  a  document  history 
is  started  (author’s  name  is  requested) 
and  a  blank  edit  screen  is  presented.  If 
the  file  exists,  the  first  page  is  presented 
on  the  screen.  Text  may  then  be  entered 
or  changes  made. 

At  any  point  in  the  system,  the  help 
key  (FI  on  the  PC)  may  be  pressed  and  a 
full  screen  of  help  is  made  available.  It  is 
not  just  a  list  of  syntax  as  with  WordStar 
but  a  full  semantic  description  of  the 
possible  actions  at  that  time.  The  help 
processor  is  fully  context  sensitive. 
Pressing  the  Esc  key  during  the  edit 
presents  a  choice  of  editing  commands 
such  as  copying  or  deleting,  finding  or 
replacing,  moving  or  inserting.  The  file  is 
saved  by  pressing  Esc  and  then  S.  The 
main  menu  is  then  reentered  and  editing, 
printing,  and  spelling  checking  may  then 
be  done.  The  print  format  can  be  set  in 
several  ways.  The  defaults  are  the  screen 
editing  parameters.  These  can  be  over¬ 


ridden  by  print  directives  in  the  text, 
embedded  format  commands,  or  console 
overrides  at  the  time  the  document  is 
printed. 

Installation  and  Maintenance 

SuperWriter  comes  pre-installed  for 
the  IBM  PC.  A  menu-driven  program  con¬ 
figures  the  system  for  a  variety  of  printers 
—  NEC,  Diablo,  Quine,  Xerox,  etc.  Other 
than  the  printer  configuration,  no  other 
installation  is  required,  A  maintenance 
program  is  provided  with  SuperWriter. 
This  program  allows  Sorcim  to  distribute 
fixes  for  possible  bugs  so  that  no  program¬ 
ming  knowledge  is  required  to  apply  the 
fixes.  Each  fix  contains  special  self-checks 
so  that  typographical  errors  are  guarded 
against.  The  maintenance  program  also 
contains  a  verification  feature  to  deter¬ 
mine  if  a  SuperWriter  program  has  been 
damaged. 

Key  Redefinitions 

Earlier  I  promised  a  method  for  using 
some  additional  PC  keyboard  keys  for 
common  editing  functions.  This  proce¬ 
dure  makes  use  of  the  key  redefinition 
facility  of  the  ANSI  support  in  PCDOS 
Version  2.0.  You  must  have  the  entry 
DEVICE=ANSI.SYS  in  the  CONFIG.SYS 
file.  I  created  a  batch  file  named  XSW.BAT 
with  the  following  contents  to  call  Super- 
Writer: 

copy  swin.key  con: 
sw 

copy  swout.key  con: 

The  file  SWIN.KEY  is  as  follows: 
<esc>  [0;73;18p 
< esc >  [0;79;21p 
<esc>  [0;8  1  ;3p 
<esc>  [0 ;1  1 7;2p 
<esc>  [ 0 ;  1 19;20p 

The  file  SWOUT.KEY  is  as  follows: 
<esc>  [0;73;0;73p 
<esc>  [0;79;0;79p 
<esc>  [0;8  1  ;0;8  ip 
<esc>  [  0;  1 1 7 ;0 ;  1  17p 
<  esc  >  [  0 ;  1  1 9  ;0 ;  1  1 9 p 

The  symbol  <esc>  is  the  escape 
character  ASCII  hex  IB.  The  file  SWIN. 
KEY  redefines  the  PgUp  (Page  Up)  key 
to  be  AR  (Ctrl-R),  End  to  be  AU  (End-of- 
Line),  PgDn  to  be  AC  (Page  Down),  Ctrl- 
End  to  be  AB  (Bottom-of-File),  and  Ctrl- 
Home  to  be  AT  (Top -of- File).  The  file 
SWOUT.KEY  changes  the  key  redefini¬ 
tions  back  at  the  end  of  the  SuperWriter 
session. 

Conclusion 

Sorcim’s  SuperWriter  is  a  very  fine, 
easy  to  use  word  processing  package,  it 
deserves  a  large  share  of  the  market.  I 
would  recommend  the  product  and  its 
supplier,  Sorcim  Corporation,  very  highly. 

(Continued  on  page  120) 
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BOOK  REVIEWS 


The  Small  Computer  Connection 

By  Neil  L.  Shapiro 

Published  by  Micro  Text/McGraw-Hill 
$15.95,  190  pages 
Reviewed  by  James  Moran* 


Subtitled  “Telecommunications  for 
the  Home  and  Office,”  this  trade  paper¬ 
back  is  packed  with  information  on  how 
to  access  telecommunications  services 
such  as  CompuServe  and  The  Source  with 
a  personal  computer. 

The  author  begins  with  two  short 
chapters  on  telecommunications  basics 
and  quickly  moves  on  to  the  main  purpose 
of  the  book  —  explaining  how  to  use  the 
many  services  that  are  available  on  nation¬ 
al  databases.  This  format  allows  the  novice 
user  to  become  familiar  with  the  concepts 
of  modems  and  telephone  networks, 
while  at  the  same  time  allowing  the  more 
knowledgeable  reader  to  find  needed 
information  without  enduring  a  course  on 
elementary  telecommunications. 

Obviously  a  well-informed  user  of  re¬ 
mote  computer  services,  the  author  uses 
his  knowledge  to  practically  demonstrate 
the  functions  of  the  major  networks.  Par¬ 
ticularly  helpful  are  a  number  of  compar¬ 
ison  charts  that  contrast  the  services  avail¬ 
able  among  networks.  This  information 
would  be  particularly  useful  to  computer 
users  who,  although  familiar  with  a  par¬ 
ticular  network,  would  like  to  access 
another  on  an  infrequent  basis. 

Another  nice  touch  is  the  abundance 
of  examples  that  show  how  to  access  the 
various  functions  within  a  network.  On 
that  basis  alone  the  book  would  quickly 
recover  its  selling  price.  Had  I  been  able 
to  find  a  book  like  this  a  few  years  ago, 
those  confusing  (and  costly)  start-up  ses¬ 
sions  on  CompuServe  could  have  been 
avoided.  To  paraphrase  the  author:  in 
telecommunications,  time  is  money. 

Throughout  the  first  half  of  the 
book,  the  author  speaks  primarily  of  the 
large  commercial  networks  and  their  uses. 
In  the  second  half,  the  topics  become 
more  advanced.  There  is  an  excellent  sec¬ 
tion  on  setting  up  one-to-one  communi¬ 
cation  between  individual  computer  users. 
The  information  presented  would  be  par¬ 
ticularly  useful  where  the  computers 
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being  used  are  made  by  different  manu¬ 
facturers.  Some  helpful  suggestions  (with 
examples)  on  how  to  handle  different 
computer  protocols  are  made  and  exam¬ 
ples  of  typical  software  interfaces  are 
shown.  Also  included  is  a  short  section 
on  implementing  a  public  bulletin  board. 

The  text  portion  of  the  book  ends 
with  a  chapter  on  advanced  techniques 
for  telecommunications.  Topics  such  as 
database  design  for  bulletin  board  access 
are  covered  here,  as  are  techniques  for 
adding  clocking  hardware  and  software 
for  unattended  network  communications. 
A  particularly  intriguing  section  in  this 
chapter  deals  with  slow-scan  television 
(SSTV)  and  Telidon  videotex.  Both  of 
these  methods  allow  for  the  generation  of 
pictures  or  graphics  on  the  monitor  screen 
when  the  computer  is  telecommunicating. 

A  useful  appendix  wraps  up  the 
book.  Included  in  it  is  a  well- organized 
list  of  public  access  message  systems  or¬ 
ganized  by  area  code.  Although  1  didn’t 
count  them,  at  least  six  hundred  are 
listed. 

In  summary,  the  book  is  useful,  well 
written,  and  understandable.  The  author, 
a  columnist  and  editor  for  Popular  Me¬ 
chanics  magazine,  has  put  his  background 
to  good  use.  This  how-to-do-it  guide  will 
be  a  useful  addition  to  the  library  of 
many  home  computerists. 


Introducing  the  UNIX  System 
By  Henry  McGilton  and  Rachel  Morgan 
Published  by  BYTE  Books/McGraw  Hill 
$18.95,  556  pages 

Reviewed  by  Dr.  Joseph  B.  Rothstein 


The  jury  is  still  out  on  the  quet 
of  Unix  for  microcomputers,  but  a  vi. 
diet  should  be  returned  before  too  much 
longer.  On  the  one  hand,  those  who  are 
familiar  with  this  operating  sy'tem/pro- 
gramming  environment  from  its  minicom¬ 
puter  implementations  are  nearly  unani¬ 
mous  in  praising  its  power,  versatility, 
and  comprehensive  set  of  utility  programs. 
On  the  other,  Unix  requires  more  memory 
than  8 -bit  personal  computers  have 
generally  had  available.  So  it’s  only  with 
the  advent  of  the  new  generation  of  16-bit 
chips  such  as  the  Motorola  MC68000  and 
Zilog  Z8000  that  we  may  see  workable 


implementations  of  Unix  for  micros. 

Unix  is  a  product  of  Bell  Labs,  the 
research  arm  of  Western  Electric  and 
AT&T,  and  was  originally  developed  for 
in-house  use,  particularly  for  text  manip¬ 
ulation  and  program  development.  It  be¬ 
came  such  a  success  among  its  users  that 
the  decision  was  made  to  license  the  sys¬ 
tem  to  academic  and  commercial  mini¬ 
computer  facilities.  Judging  by  the  num¬ 
ber  of  microcomputer  OEM’s  and  systems 
houses  that  have  hopped  on  the  Unix 
bandwagon  in  just  the  last  few  months,  it 
appears  that  Unix  will  indeed  be  a  force 
to  be  reckoned  with  in  the  micro  world 
as  well. 

Though  the  documentation  accom¬ 
panying  the  minicomputer  versions  is 
voluminous  and  wide-ranging,  personal 
computer  users  need  and  expect  more  tu¬ 
torial  material  than  is  usually  provided  by 
Western  Electric  and  its  OEM’s.  Henry 
McGilton  and  Rachel  Morgan,  the  authors 
of  Introducing  the  UNIX  System,  make 
no  claims  that  their  text  is  a  substitute 
for  existing  Unix  system  documentation; 
in  fact,  a  disclaimer  to  that  effect  appears 
on  the  first  page  of  the  Preface,  under  the 
subchapter  heading  Caveat.  But  the  same 
Preface  describes  the  intended  audience  - 
users  who  are  new  to  the  Unix  system  - 
and  such  an  audience  is  well  served  in  this 
excellent  tutorial. 

The  first  few  pages  also  offer  a  clear, 
yet  concise  overview  of  the  book’s  organi¬ 
zation,  along  with  suggestions  on  how  the 
reader  might  best  approach  reading  and 
using  the  book.  The  text  divides  neatly 
into  two  major  parts.  The  first  100  pages 
cover  the  essential  topics  and  the  key 
concepts  behind  the  Unix  system.  This  is 
done  in  three  chapters  entitled  “Getting 
Started.  .  .  “Directories  and  Files,” 
and  “Commands  and  Standard  Files.” 

The  remainder  of  the  book  discusses 
the  utilities  generally  available  on  Unix 
systems,  and  the  kinds  of  things  you  can 
do  with  them.  The  Unix  programmer’s 
“software  toolbox”  includes  electronic 
mail  facilities,  text  editors  and  formatters, 
and  program  development  tools  for  the  C 
language. 

Part  of  the  beauty  of  Unix  is  the  sim¬ 
plicity  of  its  basic  structure;  yet  its  exten¬ 
sibility  allows  the  user  to  tailor  the  system 
to  his  or  her  needs  and  imagination.  Even 
directories  —  which  in  most  micro  operat¬ 
ing  systems  are  simple  lists  of  file  names 
and  sizes  —  involve  a  rich  and  powerful 
set  of  operations  in  Unix.  For  example, 
only  one  copy  of  a  given  file  exists  on  a 
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multi-user  Unix  system;  other  user  direc¬ 
tories  may  simply  show  that  file  listed, 
with  system  pointers  to  the  master  copy 
of  the  file  in  question. 

Each  user  has  a  master  directory, 
which  can  contain  pointers  to  files  cre¬ 
ated  and  “owned”  by  that  user  or  other 
users,  or  the  directory  entry  can  point  to 
a  subdirectory,  which  may  in  turn  point 
to  files  or  to  another  level  of  subdirec¬ 
tories.  Like  many  Unix  concepts,  the  idea 
of  multi-level  directories  may  be  confus¬ 
ing  at  first,  but  the  authors  seem  to  sense 
subjects  which  most  need  extra  explana¬ 
tions,  and  provide  appropriate  background 
material  as  necessary. 

Many  of  the  facilities  described  are 
of  the  sort  micro  users  have  only  dreamed 
about.  An  example  is  the  redirection  of 
input  and  output,  in  which  the  user  can 
specify  a  file  or  device  as  the  source  or 
destination  of  most  commands.  Something 
as  simple  as  sending  the  directory  listing 
to  a  file  for  later  use  is  all  but  impossible 
on  most  micros,  but  it’s  a  snap  under 
Unix. 

More  significant  are  facilities  to 
quickly  and  easily  specify  a  jobstream  in 
which,  for  instance,  the  output  of  one 
program  serves  as  the  input  to  another, 
whose  output  serves  as  input  to  a  third, 
whose  results  are  sent  to  the  printer  —  a 
process  called  piping.  The  user  describes 
the  pipes  and  devices  or  files,  and  Unix 
does  the  rest.  Furthermore,  this  job- 
stream  can  be  performed  in  “background,” 
allowing  the  user  to  go  on  to  another  task 
while  the  system  continues  to  process  the 
jobstream  commands  until  completed, 
without  further  intervention  by  the  user. 

Unix  is  not  without  its  problems,  and 
the  authors  point  them  out,  devoting  spe¬ 
cial  attention  to  those  that  might  most 
plague  the  neophyte  user.  With  its  large 
repertoire  of  powerful  commands,  it  is 
not  difficult  to  mistakenly  tell  Unix  to  do 
something  unexpected  or  disastrous  —  and 
Unix  will  do  little  or  nothing  to  warn  or 
stop  you. 

And  since  its  primary  focus  is  on  the 
multi-user  environment,  users  of  personal 
computers  may  find  many  of  its  facilities 
cumbersome  or  of  little  value.  Ideally, 
some  systems  house  will  develop  a  version 
of  Unix  optimized  for  a  single  user.  New 
versions  of  operating  systems  such  as 
MS-DOS  2.0  (PC-DOS  on  the  IBM)  are 
reported  to  have  “Unix-like”  facilities, 
though  they  fall  far  short  of  full  Unix 
capabilities,  which  include  much  more 
than  is  described  here.  Still,  it  is  encourag¬ 
ing  to  see  designers  of  micro  software 
learning  from  the  best,  and  despite  all  her 
shortcomings,  Ma  Bell  has  some  bright 
ideas. 

One  cautionary  note  is  in  order, 
though  it  will  be  obvious  to  most  readers. 
No  text,  regardless  of  its  quality,  can  sub¬ 
stitute  for  hands-on  experience  and  prac¬ 


tice.  Though  I  was  easily  able  to  follow 
the  discussions  and  examples  in  Introduc¬ 
ing  the  UNIX  System,  I  didn’t  for  a  mo¬ 
ment  imagine  that  I  would  be  able  to 
master  Unix  the  first  time  I  tried  it.  Rein¬ 
forcement  through  repeated  use  will  be 
required  before  a  user  feels  comfortable 
with  the  variety  of  commands  and  options 
available,  particularly  since  so  many  of 
the  command  keywords  are  compact  and 
have  little  mnemonic  significance  ( Is  and 
grep  are  only  two  of  many  examples). 

But  for  an  overview  of  a  likely  con¬ 
tender  in  the  next  round  of  operating  sys¬ 
tems  wars.  Introducing  the  UNIX  System 
seems  an  excellent  place  to  start.  It’s 
an  eye-opening  tour  of  a  sophisticated 
approach  to  human/computer  interaction, 
and  it  might  change  your  views  on  the 
entire  field  of  operating  systems. 
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CP/M  EXCHANGE 


by  Robert  Blum 


I  was  recently  made  aware  of  a  series 
of  application  notes  available  from  Digital 
Research  that  cover  problem  correction 
and  the  addition  of  some  desirable  fea¬ 
tures  to  CP/M  2.2  and  CP/M  Plus.  1  thought 
they  would  fit  very  well  into  the  format 
of  the  CP/M  Exchange  and  fortunately  so 
did  DRI.  As  a  regular  feature  I  will  run 
one  note  each  month  until  the  supply 
is  exhausted.  I  think  they  will  provide 
some  useful  insight  into  how  CP/M  does 
its  job,  and  may  assist  you  in  correcting  a 
problem  or  two.  This  month’s  application 
note  deals  with  toggling  the  cntrl-P  switch 
from  within  a  submit  job. 

Of  all  the  correspondence  I  receive, 
questions  about  interfacing  to  peripheral 
devices  are  the  most  popular.  Most  of  the 
questions  are  about  serial  channels  and 
adapting  them  to  devices  not  directly 
supported  by  the  computer  manufacturer. 
This  gray  area  exists  mainly  because  of 
the  lack  of  hardware  documentation  that 
is  provided  with  today’s  personal  comput¬ 
er.  Starting  next  month  I  will  begin  a 
regular  series  on  how  the  various  manu¬ 
facturers  have  implemented  their  ports  to 
the  outside  world  and  any  driver  software 
that  I  can  acquire.  If  you  have  a  problem 
of  this  type,  drop  me  a  note  and  I  will  do 
my  best  to  answer  it. 

Intel  8080  to  Zilog  Z80 
Program  Conversion 

Over  the  years  I  have  acquired  and 
written  many  programs  that  all  seem  to 
use  a  different  dialect  of  the  original 
Intel  8080  opcodes  when  dealing  with  the 
expanded  Z80  instruction  set.  I  have  been 
forced  to  live  with  this  situation  because 
to  convert  them  by  hand  to  Zilog  opcodes 
would  take  more  effort  than  I  was  pre¬ 
pared  to  invest.  My  dreams  of  a  program 
to  do  this  job  for  me  was  realized  when  I 
came  upon  XLATE2  in  the  SIG/M  library. 
Ron  Conn,  author  of  ZCPR2  and  SYS- 
LIB,  did  an  excellent  job  of  producing 
a  program  that  will  automatically  convert 
the  standard  set  of  Intel  8080  opcodes  to 
the  Zilog  format  with  practically  no 
errors.  This  is  definitely  the  program  to 
have  if  you  want  to  standardize  your  as¬ 
sembler  source  programs  as  I  did. 

Hidden  Treasures  Revisited 

Last  month  I  talked  about  what  I 
thought  was  the  best  set  of  assembler  sub¬ 
routines  that  I  had  ever  seen.  Forget  every¬ 
thing  I  said!  After  receiving  the  most 
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recent  version  of  SYSLIB  from  SIG/M, 
I  was  ecstatic  to  find  that  it  is  even  better 
than  I  thought. 

The  version  mat  I  reported  on  last 
month  was  from  an  old  CPMUG  volume. 
I  never  did  count  the  number  of  subrou¬ 
tines  contained  in  that  library,  but  I  would 
guess  there  were  60  or  70.  The  documen¬ 
tation  was  in  the  form  of  help  files  to 
be  used  with  the  on-line  help  facility 
also  included  in  that  same  volume.  Well, 
hold  on  to  your  hats  wh  about 

the  latest  version  of  SYSLlr,.  '  - 

of  subroutines  now  totals  over  i 
even  counting  those  that  work  in  con¬ 
junction  with  ZCPR2.  The  documentation 
still  exists  in  help  file  form  in  addition  to 
two,  yes  two,  manuals  that  can  be  printed 
for  hard  copy  reference.  The  first  manual, 
SYSLIB  User  and  Reference  Manual,  is 
76  pages  long  and  thoroughly  explains 
what  each  subroutine’s  function  is  and 
how  to  use  it.  The  second  manual,  User’s 
Guide  for  SYSLIB,  is  a  tutorial  on  how  to 
effectively  use  each  routine.  The  docu¬ 
mentation  as  a  whole  is  more  than  just 
two  pounds  of  paper  and  a  lot  of  empty 
words.  It  is  well  written  and  more  than 
adequately  documents  what  I  hold  to  be 
the  most  vital  part  of  all  of  my  program 
development  tools. 

One  thought  hit  me  soon  after  read¬ 
ing  the  table  of  contents  of  the  first 
manual.  With  a  good  set  of  macros  I 
could  create  a  high  level  language  of  my 
own  design,  meeting  my  own  program¬ 
ming  goals,  while  still  maintaining  the 
high  level  of  efficiency  inherent  to  assem¬ 
bler  programs. 

Take  it  from  me,  if  you  are  intent  on 
writing  assembler  programs  you  need 
SYSLIB. 


CP/M  Plus  DPB  Macro  Fix 

A  few  months  ago  I  ran  some  com¬ 
ments  from  a  reader  who  had  brought  up 
CP/M  Plus.  One  of  the  problems  that  he 
ran  into  was  that  the  supplied  DPB  macro 
would  not  handle  a  drive  capacity  of 
greater  than  8  megabytes.  Thanks  to 
William  Nichparenko  of  Aptos,  California, 
there  is  a  short  modification  that  can  be 
made  to  the  DPB  macro  to  alleviate  this 
problem.  Bill  writes  .  .  . 

“Enclosed  is  a  correction  for  the  8 
megabyte  limit  to  the  drive  size  imposed 
by  the  Disk  Parameter  Block  (DPB) 
macro  in  Digital  Research’s  CP/M  Plus 
system. 

“The  limit  arises  when  the  DSM  pa¬ 


rameter  (related  to  the  file  size)  is  calcu¬ 
lated.  The  simplified  expression  for  DSM 
is  given  [in  Figure  1  (page  104)] . 

“This  expression  has  been  arranged 
to  minimize  multiplications  since  they 
are  what  limit  the  dynamic  range  of  the 
DSM  parameter.  Since  RMAC  has  an  up¬ 
per  limit  on  the  arithmetic  for  expression 
evaluation  of  65536,  any  product  that 
exceeds  this  limit  creates  errors.  For 
example,  a  20  megabyte  drive  would 
have  2441  tracks  and  the  product  of 
Tracks  *  SectorsPerTrack  =  78125. 

“The  first  assumption  that  is  made  is 
that  the  block  size  is  an  integral  multiple 
of  the  sector  size.  This  is  true  for  all  cur¬ 
rent  drives  that  I  know  of,  and  CP/M 
would  not  be  able  to  function  if  this  were 
not  true.  This  implies  that  the  expression 
(Block Size/SectorSize)  will  always  be  a 
whole  integer. 

“One  interesting  aside  is  that  just  the 
simple  rearrangement  of  the  expression 
for  DSM  highlights  the  fact  that  the 
upper  limit  on  the  drive  size  is  sector  size 
dependent.  Thus,  the  limit  is  8  mega¬ 
bytes  for  a  sector  size  of  128  bytes,  16 
megabytes  for  256  byte  sectors,  etc. 

“What  is  really  needed  is  some  sim¬ 
ple  method  for  RMAC  to  do  32-bit 
arithmetic.  I  am  indebted  to  Dan  Ross  of 
Succinct  Systems  for  suggestion  of  the 
following  algorithm. 

“Before  the  multiplication  of  system 
tracks  times  the  number  of  sectors  per 
track  is  performed,  each  variable  is  split 
into  a  high  and  low  byte,  and  the  product 
then  done.  The  resulting  expression  is 
only  slightly  more  complicated  than  the 
original,  but  will  allow  the  macro  to  func¬ 
tion  up  to  the  512  megabyte  drive  limit 
inherent  in  CP/M  Plus. 

“Let 

(Total Tracks  -  Offset)  =  (Tm*256  +  Tl) 
SectorsPerTrack  =  (Zm*256  +Zl) 

where  Zm  is  the  most  significant  byte  of 
the  16-bit  SectorsPerTrack  and  Z1  is  the 
least  significant  byte  of  the  16-bit  Sectors¬ 
PerTrack  with  Tm  and  Tl  defined  in  a 
similar  manner  for  the  track  variable.  The 
product  of  the  tracks  times  sectors  now 
becomes: 

(Tm*256+Tl)(Zm*256+Zl)  = 

Tm*Zm*256*256  + 

(TmZl  +  TlZm)*256  +  T1Z1 

“This  expression  is  still  very  unwieldy 
since  we  must  be  content  with  the  prod¬ 
uct  256*256  wich  is  already  65536. 
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Thus,  we  need  to  make  one  more  simpli¬ 
fying  assumption,  that  the  number  of 
sectors  per  track  is  never  greater  than 
256,  thus  Zm  =  0.  This  results  in  the  very 
simple  expression  for  DSM: 

DSM  =  Zm*Zl  *(256/Mblk)  + 

( T 1  *Z1)/Mblk  -  1 

where  Mblk  =  Block  Size /Sector  Size. 

“This  is  a  very  reasonable  assumption 
to  make  since  all  drives  that  I  currently 
know  of  have  less  than  256  sectors  per 
track.  Since  this  is  a  possible  source  of 
error  in  the  far  future,  the  macro  can 
provide  a  warning  to  the  user  if  Zm  is  not 
zero.  In  addition  the  macro  will  provide  a 
warning  to  the  user  if  DSM  exceeds  the 
maximum  value  that  CP/M  Plus  can  ac¬ 
commodate,  which  is  255  for  IK  block 
size  and  32767  for  2K  to  16K  block 
sizes.” 

Listing  One  (page  105)  contains 
his  changes  to  the  current  DPH  macro 
that  need  to  be  made  to  implement  the 
above  correction. 


Quicker  Submit  File  Truncation 

David  Kirkland  of  Houston,  Texas, 
recently  wrote  to  share  a  quicker  way  to 
truncate  records  from  the  end  of  a  submit 
file.  Dave  writes  .  .  . 

“I  was  interested  to  read  the  item 
concerning  the  SKIPIF  command  in  the 
August  CP/M  Exchange  because  I  had  re¬ 
cently  been  working  on  a  similar  program 
myself. 

“There  is  a  quicker  (but  somewhat 
sneakier)  way  to  truncate  the  last  record 
from  the  active  $$$.SUB  file  in  order  to 
skip  the  next  command.  John  Ramsey 
copied  all  of  the  file  except  for  the  last 
record  to  produce  the  truncated  file.  The 
quicker  way  is  to  coax  the  BDOS  to 
truncate  the  file  in  place  by  having  the 
directory  entry  for  the  file  altered.  One 
problem  with  this  method  is  that  it  does 
not  work  for  files  of  more  than  one 
extent  (128  records).  However,  the  CCP 
(and  ZCPR)  will  not  properly  handle  a 
$$$.SUB  file  consisting  of  more  than  128 
records  anyway,  so  it’s  no  great  loss.  I 
don’t  know  if  the  trick  of  modifying  the 
system  byte  in  the  FCB  to  cause  the 
BDOS  to  write  the  FCB  back  to  the  direc¬ 
tory  on  a  close  is  common  knowledge, 
but  that’s  what  the  CCP  and  ZCPR  do 
themselves. 

“I  have  found  that  the  SKIPNIF  and 
QUITIF  functions  combined  with  nested 
submits  allow  me  to  do  all  sorts  of  useful 
things  easily;  quite  a  step  from  the  origi¬ 
nal  bare-bones  submit  functions.  I  also 
would  recommend  one  further  change 
that  I’ve  made  to  my  system.  I  put  the 
$$$.SUB  file  on  a  RAM  disk.  This  one 
step  can  save  a  lot  of  waiting  and  a  lot  of 
wear  and  tear  on  your  disk  drive  arm,  to 
boot.” 

Dave’s  comment  about  zeroing  the 


S2  byte  of  the  FCB  to  mark  it  for  writing 
to  the  directory  is  characteristic  of  a  few 
internal  tricks  that  can  be  used  with 
CP/M.  One  reason  that  they  are  not  com¬ 
monly  known  is  that  they  are  not  docu¬ 
mented.  Which  brings  up  a  subject  that 
must  be  considered  before  charging  ahead 
and  using  trick  code.  DR  purposely  omit¬ 
ted  documentation  on  some  of  the  fea¬ 
tures  of  CP/M  because  they  are  considered 
internal  techniques  only  to  be  used  by 
the  operating  system.  And  since  they 
aren’t  documented,  that  means  they  may 
not  work  in  subsequent  releases.  The  fact 
of  the  matter  is  this:  if  you  use  it  and 
later  it  suddenly  stops  working,  don’t 
gripe.  DR1  is  only  responsible  for  what  is 
documented,  not  what  the  hacker  has 
found  out  by  prodding  into  the  object 
code. 

I  must  admit  that  I  am  as  guilty  as 
the  next  person  of  finding  and  using 
tricks,  but  I  have  confidence  that,  if 
something  suddenly  changes,  finding  a 
new  way  can’t  be  any  more  difficult  than 
finding  the  original  trick.  Those  are  fa¬ 
mous  last  words  if  I  ever  heard  them.  The 
choice  is  yours. 

Dave’s  changes  for  John  Ramsey’s 
SKIPIF  program  are  contained  in  Listing 
Two  (page  106).  Next  month  I  will  run 
Dave’s  SKIPNIF  program. 

CP/M  Application  Note  14 

For:  CP/M  2.2 

Copyright  ©  Digital  Research,  Inc.  1982. 
All  rights  reserved.  Text  adapted  from  the 
original. 

When  using  the  SUBMIT  facility  for 
batching  job  streams,  no  facility  is  pro¬ 
vided  to  turn  the  CTRL-P  toggle  on  and 
off  from  within  the  SUBMIT  file.  Even 
though  there  is  a  patch  for  SUBMIT  that 
forces  it  to  accept  control  characters 
when  preceded  by  a  circumflex,  SUB¬ 
MIT  does  not  act  on  a  CTRL-C  or  a 
CTRL-P. 

The  assembly  language  program  that 
follows,  CNTLP  (Listing  Three,  page 
106),  will  turn  the  CTRL-P  function  on 
or  off  within  a  SUBMIT  file.  The  same 
assembly  code  can  also  be  used  from 


within  an  application  program  or  when 
loaded  and  saved /executed  directly  from 
the  console  to  perform  the  same  function. 
If  XSUB  is  to  be  active  in  the  SUBMIT 
file,  CNTLP  must  be  executed  before 
XSUB.  Even  though  the  CP/M  V2.2 
Operating  System  Manual  states,  “The 
XSUB  command  is  included  as  the  first 
line  of  your  submit  file.  .  .,”  this  is  not 
necessary.  If  it  is  necessary  to  use  XSUB 
and  also  to  alter  the  CTRL-P  status 
multiple  times  in  the  same  submit  pro¬ 
cedure,  XSUB  can  be  deactivated  by 
using  the  assembly  language  program  in 
Listing  Four  (page  109).  This  program 
also  turns  off  CTRL-P  if  it  is  on  when 
used. 

When  using  CNTLP,  if  the  ^P  toggle 
is  off,  it  is  turned  on;  if  on,  it  is  turned  off. 
An  appropriate  message  is  output  to  the 
console  and  also  echoed  to  the  list  device 
indicating  the  CTRL-P  function  status. 

CNTLP  calculates  the  location  of  the 
AP  toggle  byte  in  the  BDOS  by  first  get¬ 
ting  the  BDOS  address  from  the  jump 
instruction  located  at  05  H  and  adding 
02FEH  to  that  address.  At  this  address 
there  must  be  a  verifiable  four-byte  se- 
qunce  or  an  error  message  is  output  to  the 
console  indicating  that  the  BDOS  could 
not  be  found.  As  an  operational  note 
here,  if  this  occurs  it  means  that  some 
other  program  exists,  such  as  DDT  or 
XSUB,  that  has  already  storage- protected 
itself  by  altering  the  BDOS  entry  point  at 
location  05  H.  The  calculated  address  is 
then  altered  to  point  to  the  CTRL-P 
function  byte,  and  an  exclusive  or  is  per¬ 
formed  on  it  to  turn  ^P  on  or  off  depend¬ 
ing  on  its  initial  status. 


(Listing  begins  on  page  105) 


DSM  =  ((TotalTracks  -  Offset)  *  SectorsPerTrack)/(BlockSize/SectorSize)  -  1 

Where  TotalTracks  =  Total  number  of  usable  tracks  on  the  drive 
Offset  =  Number  of  tracks  allocated  for  system  use 

SectorsPerTrack  =  Total  number  of  sectors  per  track 
SectorSize  =  Total  number  of  bytes  per  sector 

BlockSize  =  CP/M  defined  block  size  (1024,  2048,  etc.) 

Figure  1. 
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CP/M  Exchange  (Text  begins  on  page  102) 

Listing  One 

;First  add  a  declaration  of  new  local  variables  and  maybe  a  few  lines 
j  telling  the  reasons  for  the  change  and  a  reference  to  documentation 

;  explaining  the  change  at  greater  length. 

LOCAL  Tm.Tl , Zm.Zl .Mblk 


;  Next 

define  the 

variables 

Tm 

SET 

HIGH  ( ?  t rks- ? 

off) 

T  1 

SET 

LOW  ( ?  trks- ? 

off) 

Zm 

SET 

HIGH  ?pspt 

Z1 

SET 

LOW  ?  p s  p  t 

Mblk 

SET 

?bls/?psize 

;  Add 

warning  for 

too  many  sectors 

per 

track 

IF 

Zm  NE  0 

’ War nin 

g ,  DSM  parameter 

inva 

lid  due  to 

sectors/ track  >  256' 

ENDIF 

5  Repl 

ace  previous 

calculation  for 

?dsm 

with  the 

updated  calculation 

?  dsm 

set 

Tm*Zl*(256/Mblk)  + 

(T1*Z1 ) /Mblk  -  1 

;  Add 

warning  for 

drive  size  too  big 

IF 

? bis  NE  1024 

IF  ?dsm  >  32767 

'Warning,  Drive  size  too  big  for  CP/M' 
ENDIF 


ENDIF 

End  Listing  One 


Listing  Two 

OPEN 

EQU 

15 

; BDOS  OPEN  FUNCTION 

CLOSE 

EQU 

16 

; BDOS  CLOSE  FUNCTION 

SKIP 

EQU 

$ 

MVI 

C .OPEN 

; OPEN  $$  $ . SUB  FILE 

LXI 

D .SUBFILE 

> 

CALL 

BDOS 

I 

INR  A 

RZ 

LXI  H , SUBFILE+14 

MVI  M , 0  ; ZERO  THE  S2  BYTE  OF  THE  FCB  TO  FORCE 

; A  WRITE  OF  THE  MODIFIED  FCB  BACK  TO 


; CHECK  IF  $$$.SUB  EXISTS 
; RETURN  IF  NOT 
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THE  DIRECTORY.  NOW  POINT  TO  THE  RC 
FIELD  OF  THE  FCB  TO  DECREMENT  THE 
NUMBER  OF  RECORDS  IN  $$$.SUB. 


INX 

H 

DCR 

M 

MVI 

C, CLOSE 

; CLOSE 

LXI 

D , SUBFILE 

;  FCB 

CALL 

BDOS 

$  $  $ .SUB  TO  REWRITE  THE  MODIFIED 

End  Listing  Two 


Listing  Three 


;  Program 

to  turn 

list  device 

BDOS 

EQU 

5H 

BDOSA 

EQU 

BDOS+1 

PSTR 

EQU 

9 

TESTOFF 

EQU 

02FEH 

LISTCP 

EQU 

ODH 

MVIC 

EQU 

03  EH 

CR 

EQU 

ODH 

LF 

EQU 

OAH 

CNTLP  : 

ORG 

0100H 

LHLD 

BDOSA 

LXI 

D .TESTOFF 

DAD 

D 

LXI 

D , STRING 

COMPARE : 

LDAX 

D 

ORA 

A 

JZ 

OK 

CMP 

M 

INX 

H 

INX 

D 

JZ 

COMPARE 

ERROR: 

MVI 

C , PSTR 

LXI 

D .ERRORMSG 

JMP 

BDOS 

OK: 

MVI 

L .LISTCP 

n  and  off  from  SUBMIT  procedure 


BDOS  JUMP  INSTRUCTION 
BDOS  ENTRY  ADDRESS 
PRINT  STRING  FUNCTION 
OFFSET  FOR  VERIFICATION 

~P  OFFSET  IN  PAGE 
MVI  C,X  INSTRUCTION 
CARRIAGE  RETURN 
LINE  FEED 


; PICK  UP  ADDRESS  OF  BDOS  IN  HL 
; OFFSET  OF  ~P  PAGE  IN  DE  FOR  ADD 
;  HL=  COMPARE  AREA  IN  BDOS 
;  DE=  COMPARE  STRING 


IS  CHARACTER  A  0? 

YES  ,  WE'RE  DONE 
IS  BDOS  SAME  AS  STRING 
NEXT  BYTE 

BDOS  =  STRING  KEEP  LOOPING 


ELSE  PRINT  ERROR  MESSAGE 
RETURN  TO  CCP  FROM  BDOS 


; LI STCP  PAGE  OFFSET 


(Continued  on  page  108) 
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CP/M  Exchange  (Listing  continued,  text  begins  on  page  102) 

Listing  Three 


MVI 

A,1 

; TOGGLE  ~P  BYTE  ON  OR 

OFF 

SUB 

M 

; TRUE  =  1,  FALSE  =  0 

MOV 

M,  A 

; PUT  RESULTS  BACK  IN  MEMORY 

CPI 

00H 

;  SEE  IF  ON  OR  OFF 

JZ 

OTHERMSG 

;  TO  ISSUE  APPROPRIATE 

MESSAGE 

LXI 

D  ,  ONMSG 

;~P  TURNED  ON 

JMP 

PRINT 

; GO  AROUND 

OTHERMSG: 

LXI 

D, OFFMSG 

; ~P  TURNED  OFF 

PRINT: 

MVI 

C , PSTR 

; PRINT  SIGN-ON  MESSAGE 

JMP 

BDOS 

; RETURN  TO  CCP  FROM  BDOS 

ONMSG  : 

DB 

CR,LF, ' (~P 

turned  on ) $ ' 

OFFMSG : 

DB 

CR,LF, ' (~P 

turned  of  f  )  $  ' 

ERRORMSG : 

DB 

CR,LF, 'Unable  to  find  BDOS$' 

STRING : 

DB 

RET ,MVIC,1,JMP,0 

END 

End  Listing  Three 

Listing  Four 

9 

;  Program  to  Deactivate  XSUB  and  Reset  ~P  function 

) 

DEXSUB : 


ORG 

0100H 

BDOS 

EQU 

05H 

; BDOS  LOCATION  IN  BASE  PAGE 

CR 

EQU 

ODH 

; CARRIAGE  RETURN 

LF 

EQU 

OAH 

; LINE  FEED 

MVI 

C ,  9 

; PRINT  STRING  =  FUNCTION  9 

LXI 

D  ,  MSG 

9 

CALL 

BDOS 

9 

MVI 

C,0 

; SY  STEM  RESET  =  FUNCTION  0 

JMP 

BDOS 

; E XIT  BDOS  TO  CCP 

MSG: 

DB 

CR , LF , * (XSUB 

deactivated;  ~P  turned  off  if  on)$' 

END 

End  Listing  Four 
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16-BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


IBM  PC  Technical  Reference 

IBM  has  quitely  released  a  drastic 
revision  of  the  popular  Technical  Refer¬ 
ence  Manual  for  the  Personal  Computer. 
It  can  be  recognized  on  the  store  shelves 
because  of  a  white  “2.02”  sticker  on  its 
spine,  and  weighs  in  at  some  660  pages 
as  opposed  to  the  older  version’s  360  odd 
pages.  Most  of  the  sections  have  been 
expanded;  material  on  the  Intel  Numeric 
Coprocessor  has  been  added;  the  BIOS 
listings  for  the  hard  disk  driver  are 
included;  and  the  tables  and  schematics 
for  the  various  new  expansion  cards  and 
the  new  256  Kbyte  mother  board  are 
also  present.  There  is  no  provision  for 
buying  an  updated  page  set  for  your  old 
manual  .  .  .  you’ll  just  have  to  spend  the 
$36  to  get  another  one. 

We  don’t  have  room  in  this  month’s 
column  to  describe  all  of  the  interesting 
new  additions  to  the  Technical  Manual, 
but  here  is  one  example.  On  page  2-11, 
tucked  away  in  the  back  next  to  the 
ROM  BIOS  listing,  is  a  description  of  a 
hitherto  undocumented  feature  of  the 
system  that  is  used  to  install  the  hard  disk 
driver  at  cold  start  time.  It  is  titled  “Adap¬ 
ter  Cards  with  System -Accessible  ROM 
Modules,”  and  describes  how  after  the 
BIOS  sets  up  its  interrupt  vectors  during 
the  initialization  sequence,  it  scans  the 
memory  space  from  0C8000H  to  0F4000H 
in  2  Kbyte  blocks  looking  for  valid  ROM 
software. 

A  valid  ROM  routine  is  defined  to 
begin  as  follows: 

byte  contents 

0  055H 

1  OAAH 

2  length  indicator 

The  length  indicator  represents  the  num¬ 
ber  of  512-byte  blocks  in  the  ROM,  i.e., 
length/5  12.  A  checksum  over  the  code  in 
the  ROM  is  also  done  by  the  BIOS  scan 
routine;  each  byte  is  summed  modulo  hex 
100  and  the  total  must  be  zero.  Assuming 
the  ROM  passes  these  validity  tests,  the 
BIOS  performs  a  far  call  to  byte  3  of  the 
ROM,  which  must  therefore  be  executa¬ 
ble  code.  The  ROM  is  then  free  to  take 
over  system  interrupts  as  needed  in  order 
to  substitute  its  own  drivers  for  the  nor¬ 
mal  system  device  drivers.  Finally,  the 
ROM  should  return  control  to  the  BIOS 
initialization  sequence  via  a  “Far  Return.” 

This  is  really  a  nifty  capability.  It  can 
be  used  by  third  party  expansion  card 


manufacturers  to  provide  enhanced  video 
graphics  cards  or  disk  controllers  with  the 
driver  software  in  PROM,  rather  than 
having  to  supply  driver  files  on  diskette 
and  count  on  the  user  to  install  them 
properly.  It  can  also  be  used  by  you,  the 
sophisticated  PC  owner  and  loyal  reader 
of  this  column,  to  permanently  install 
your  own  software  inventions,  test  rou¬ 
tines,  character  tables,  and  who  knows 
what  else  into  those  empty  EPROM  slots 
on  the  mother  board. 

The  IBM  PC  Exhibitions 

I  was  tempted  to  include  a  few  com¬ 
ments  here  after  the  PC-83  Show  which 
was  put  on  in  June  by  Northeast  Exhibi¬ 
tions  in  San  Francisco,  but  decided  to 
desist  so  as  not  to  prejudge  the  PC  Faire 
by  Jim  Warren’s  organization  that  was 
scheduled  for  August.  But  now  it  can  be 
told,  since  both  shows  are  safely  over 
with  —  they  were  both  duds. 

The  number  of  attendees  was  low  for 
both,  and  with  good  reason:  there  was 
very  little  that  was  interesting  to  see.  All 
the  PC  oriented  magazines  had  their 
traditional  booths,  as  did  the  disk  media 
manufacturers,  the  RAM  expansion  board 
builders,  the  DBASE  II  utility  sellers,  the 
discount  software  mail  order  marketers, 
etc.  —  yawn  .... 

But  booths  displaying  innovative 
hardware  products  or  novel  new  programs 
were  scarce  as  could  be.  In  fact,  the  only 
booth  I  discovered  at  PC  Faire  which 
made  the  trip  worthwhile  belonged  to 
Morgan  Computing  Co.  They  were  demon¬ 
strating  their  new  “Professional  BASIC,” 
which  allows  full  use  of  the  8088  memory 
space  and  includes  8087  support,  syntax 
checking  at  entry  time,  a  window- oriented 
debugger,  conditional  breakpoints,  and 
upward  compatibility  with  IBM  PC  Basic. 
This  product  makes  Microsoft  Basic  look 
pretty  old-fashioned.  Interestingly,  Pro¬ 
fessional  BASIC  was  offered  to  both 
Microsoft  and  Digital  Research  by  its 
author,  and  was  turned  down  —  perhaps 
both  companies  think  they  are  making 
enough  money  already!  Morgan  was  also 
showing  a  very  impressive  window- 
oriented  assembly  language  debugger 
called  “Trace-86,”  which  we  will  cover 
in  greater  detail  in  an  upcoming  column. 


68000  News 

We  have  finally  received  copies  of 
two  different  CP/M-68K  implementations 


for  the  CompuPro  68000  system,  one  by 
Gifford  Engineering  and  the  other  by 
CompuPro  itself.  The  contrast  between 
the  two  is  quite  striking.  Gifford  chose  to 
write  all  of  the  necessary  utilities  and  the 
CP/M  BIOS  in  C;  CompuPro  did  the  BIOS 
using  the  traditional  assembly  language 
approach.  Perhaps  it’s  a  coincidence,  but 
the  Gifford  implementation  works  very 
smoothly  while  the  CompuPro  release  is 
ridden  with  severe  bugs:  the  system  fails 
to  boot  from  distribution  disk  #1  as 
described  in  the  manual,  printer  support 
for  the  Interfacer  4  card  does  not  work, 
and  the  one  of  the  console  status  BDOS 
functions  for  the  Interfacer  4  card  hangs 
up  the  system  irretrievably  -  to  name 
but  a  few. 

On  another  subject  altogether,  we 
recently  received  an  outraged  letter  from 
a  Cromemco  68000  system  purchaser 
who  had  divined  why  the  performance  of 
the  68000  Cromix  operating  system  is  so 
poor.  It  turns  out  that  most  of  Cromix  is 
still  compiled  to  Z80  machine  code,  and 
the  68000  part  of  the  dual  CPU  card  is 
only  in  use  while  the  application  program 
is  executing.  With  this  little  tidbit  in  mind, 
you  can  go  back  and  read  the  Cromemco 
advertisements  about  their  super- duper 
enhanced  Cromix  for  the  68000  with  a 
new  outlook. 


Floating  Point  Benchmarks 

The  floating  point  benchmark  figures 
from  Bill  Savage  that  I  included  in  the 
September  column  have  generated  a  great 
deal  of  mail  from  readers.  In  a  few  months 
I  will  gather  together  all  of  the  additional 
contributed  benchmark  results  and  pub¬ 
lish  them  in  a  new  table.  In  the  meantime, 
I  am  providing  a  Pascal  and  Forth  version 
of  the  same  benchmark  so  that  everyone’s 
figures  will  be  comparable  (see  Listing 
One,  page  112). 


MS-DOS  COM  File  Loader 

This  month,  I’m  including  a  useful 
utility  called  BIGLOAD  written  by  Rick 
Wilton  for  MS-DOS  users  (Listing  Two, 
page  1 12).  It  turns  out  that  MS-DOS  uses 
the  “block  read”  function  to  load  a  COM 
file,  and  can’t  handle  such  a  file  if  it’s 
larger  than  65535  bytes  (although  an 
EXE  file  of  almost  any  size  can  be  loaded 
successfully).  Some  languages,  such  as  our 
PC/FORTH+  package,  allow  the  user  to 
write  a  new  executable  image  with  their 
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own  precompiled  extensions,  and  files  of 
this  type  can  get  quite  large.  BIGLOAD 
allows  you  to  load  such  a  COM  file, 
optionally  supplying  a  second  filename 
which  will  be  filled  into  the  default  file- 
control-block  at  005CH. 

BIGLOAD  illustrates  a  number  of 
useful  techniques  for  MS-DOS  assembly 


language  programmers:  using  the  block 
read  functin  27H,  setting  up  a  new  program 
segment  prefix  and  terminate  address,  and 
transferring  control  to  a  “spawned”  pro¬ 
gram.  The  latter  two  functions  can  be 
done  more  simply  under  DOS  2.0  via  the 
new  “Load  or  Execute  a  Program”  service, 
function  04BH,  but  this  method  was  not 


used  in  BIGLOAD  in  order  to  preserve 
compatiblity  with  DOS  1.0  and  1.1. 

(Listings  begin  below) 


16-Bit  Toolbox  (Text  begins  on  page  110) 

Listing  One 

PASCAL  version,  contributed  by  Jeffrey  Speiser  of  San  Diego, 
California: 


PROGRAM  SAVAGE (INPUT, OUTPUT) ; 

{SPEED  AND  ACCURACY  TEST  FOR  FLOATING  POINT} 

{REF:  DR.DOBB'S  JOURNAL,  SEPT.  1983,  PP.  120-122} 

CONST 

I LOOP=2500 ; 

VAR 

I : INTEGER; 

A : REAL8 ; 

{TNDRQQ  IS  DOUBLE  PRECISION  TANGENT} 

FUNCTION  TNDRQQ  (CONSTS  A:  REAL8 ) : REAL8  ;  EXTERN; 

BEGIN 

WRITELN ( 'START') ; 

A: =1. 0 ; 

FOR  I : =1  TO  I  LOOP-1  DO 
BEGIN 

A: =TNDRQQ (ARCTAN (EXP  (LN (SQRT ( A*A) ) ) ) ) +1; 

END; 

WRITELN ( 'A=' , A  : 20:14); 

WRITELN ( 'DONE' ) ; 

END. 


FORTH  version,  as  run  on  PC/FORTH  with  8087  floating  point  support. 
This  uses  the  8087  functions  in  the  simplest  mode  with  no  chaining  of 
operations  on  the  8087's  internal  stack: 


(FN)  FDUP  F*  FSQRT  FLN  FE**X  FATAN  FTAN  ; 

FN  2500  1  DO  (FN)  1 .  E  0  F+  LOOP  ; 

SAVAGE  1.  E  0  FN  CR  . "  Result:  "  F.  ; 

End  Listing  One 


Listing  Two 

na»e  bigload 
page  55,132 

title  ’BIGLOAD  -  load  .COH  file  bigger  than  G4K’ 
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• 

» 

1 

;  BIGLOAD  -- 

load  .COM  file  bigger  than  64K 

5  1  for  IBM  PC  under  PC-DOS  1.1 

or  2.0  ) 

1  Version  1 

March  1983 

» 

;  Richard  Hilton 
;  Laboratory  Microsystems 
;  4147  Beethoven  Street 
;  Los  Angeles,  CA  90066 

• 

f 

0000 

I 

cseg  segment  byte 

astute  cs:c5eg,dsicseg 

0000 

bigload  proc 

far 

I  sets  up  far  return  ... 

0100 

org 

lOOh 

=  000D 

cr 

egu  Odh 

}  carriage  return 

=  O00A 

If 

egu  Oah 

j  line  feed 

0100 

BA  01AF  R 

start:  aov 

dx,  off  set  lesO 

;  startup  aessage 

0103 

B4  09 

10V 

ah, 9 

0105 

CD  21 

int 

21h 

0107 

33  02 

xor 

dx ,  dx 

;  zero  DX 

0109 

B4  25 

■ov 

ah , 25h 

}  set  terminate  address  ... 

010B 

B0  22 

eov 

al,22h 

;  ...  for  new  prograa  segaent 

0100 

CD  21 

int 

21h 

010F 

BA  0203  R 

•ov 

dx, offset  endofs  ;  offset  to  end  of  this  loader 

0112 

B1  04 

■ov 

cl, 4 

)  no  of  bits  to  shift 

0114 

03  EA 

shr 

dx,cl 

i  convert  byte  addr  to  paragraph 

0116 

42 

inc 

dx 

;  offset  of  1st  available  segaent 

0117 

8C  C8 

■ov 

ax,cs 

)  current  segment  to  AX 

0119 

03  DO 

add 

dx ,  ax 

;  actual  value  of  1st  available  segaent 

01  IB 

89  16  0201  R 

■ov 

useg,dx 

5  save  it  for  later  ... 

01  IF 

8E  C2 

iOV 

es,dx 

;  ...  and  for  subsequent  »ove 

0121 

B4  26 

■ov 

ah, 26h 

;  call  to  DOS 

0123 

CD  21 

int 

21h 

;  create  nett  prograa  segaent 

0125 

BE  006C 

■ov 

si ,6ch 

i  2nd  para*  FCB  in  current  segment 

0128 

BF  005C 

■ov 

di,5ch 

;  1st  paraa  FCB  in  new  segaent 

0128 

B9  000C 

■ov 

cx,0ch 

;  byte  count  for  aove 

012E 

F3/  A4 

repz 

■ovsb 

;  copy  the  filenaae 

0130 

BC  C9 

AOV 

ax,cs 

}  copy  current  code  seg  ... 

0132 

8E  08 

■ov 

ds,ax 

;  ...  to  DS 

0134 

BA  005C 

■ov 

dx ,  5ch 

;  DSsDX  points  to  FCB  of  .COM  file 

0137 

8B  DA 

AOV 

bx ,  dx 

;  lake  FCB  addressible 

0139 

C6  47  09  43 

AOV 

byte  ptr  9  Ebx 3 , 43h  ;  force  a  "C*  ... 

0130 

C6  47  OA  4F 

AOV 

byte  ptr  10  [bxl,4fh  j  ...  an  ‘O’  ... 

0141 

C6  47  OB  40 

AOV 

byte  ptr  11  Ebx 3 , 4dh  ;  ...  and  an  ‘M*  into  the  filename 

0145 

B4  OF 

AOV 

ah,0fh 

)  open  the  .COM  file 

0147 

CD  21 

int 

21h 

0149 

OA  CO 

or 

al,al 

i  test  return  code 

014B 

75  41 

jnz 

exitl 

1  exit  if  non-zero 

0140 

C7  47  21  0000 

■ov 

word  ptr  33  Cbx3,0000  i  zero  the  rando*  ... 

0152 

C7  47  23  0000 

AOV 

word  ptr  35  Ebx 3,0000  ;  ...  record  field  in  the  FCB 
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16-Bit  Toolbox  (Listing  continued,  text  begins  on  page  1 10) 

Listing  Two 


0157 

A1  0201  R 

aov 

ax,useg 

5 

copy  the  new  segaent  into  ... 

01 5A 

8E  DO 

aov 

55,  ax 

5 

...  reg  SS 

01 5C 

BC  0100 

aov 

sp,100h 

a 

9 

now  SSiSP  can’t  be  traapled  on 

015F 

8B  IE  0201  R 

aov 

bx,useg 

) 

initialize  BX  to  keep  track  ... 

0163 

83  C3  10 

add  bx , lOh 

;  ...  of  the  current  DTA 

0166 

BE  DB 

aov 

ds,bx 

set  up  DS: DX  to  point  to  the  DTA 

0168 

33  D2 

xor 

dx,dx 

016A 

B4  1A 

aov 

ah, 1  ah 

set  up  DOS  call  and  do  it 

016C 

CD  21 

int 

21h 

01 6E 

B9  0100 

loop!: 

aov 

cx,100h 

a 

9 

nuaber  of  records  of  length  80h 

0171 

8C  C8 

aov 

ax,cs 

a 

9 

copy  current  CS  to  DS 

0173 

8E  D8 

aov 

ds,ax 

0175 

BA  005C 

aov 

dx,5ch 

1 

DS: DH  points  to  FCB  of  . C0H  file 

0178 

B4  27 

aov 

ah,27h 

a 

9 

do  randoa  block  read 

017A 

CD  21 

int 

21h 

017C 

A8  01 

test 

alyl 

5 

end  of  file? 

017E 

75  17 

jnz 

exit2 

i 

yes,  so  exit 

0180 

81  C3  0800 

add 

bx,800h 

1 

increaent  location  of  DTA 

0184 

8E  DB 

aov 

ds,  bx 

1 

copy  to  DS 

0186 

33  D2 

xor 

dx,dx 

5 

DSiDX  now  points  to  next  DTA 

0188 

B4  1A 

aov 

ah ,  1  ah 

1 

set  up  DOS  call  to  set  DTA 

018A 

CD  21 

int 

21h 

018C 

EB  E0 

loopl 

5 

do  it  again 

018E 

BA  01D2  R 

exitl: 

BOV 

dx, offset  aesl 

1 

"file  not  found" 

0191 

B4  09 

aov 

ah, 9 

1 

write  to  terainal 

0193 

CD  21 

int 

2ih 

0195 

CD  20 

int 

20h 

1 

exit  to  DOS 

0197 

8C  C8 

exit2: 

aov 

ax,cs 

1 

copy  CS  to  BS 

0199 

8E  D8 

aov 

ds,ax 

019B 

BA  01EA  R 

aov 

dx,offset  aes2 

! 

"file  loaded* 

019E 

B4  09 

aov 

ah, 9 

a 

9 

write  aessage  to  terainal 

01A0 

CD  21 

int 

21h 

01A2 

A1  0201  R 

aov 

ax,useg 

5 

set  up  registers  for  new  segaent 

01A5 

8E  D8 

BOV 

ds,ax 

01A7 

8E  CO 

aov 

es,ax 

01A9 

50 

push 

ax 

i 

push  new  CS  onto  stack 

01AA 

B8  0100 

aov 

ax,100h 

01AD 

50 

push 

ax 

push  offset  onto  stack 

01AE 

CB 

ret 

» 

FAR  return  causes  CS: IP  to  be  set 

01 AF 

0D 

0A 

44 

4F 

53 

20 

aesO 

dta 

cr, If , ’DOS  2.0  Multi -segaent  loader  ...4’ 

32 

2E 

30 

20 

4D 

75 

6C 

74 

69 

2D 

73 

65 

67 

6D 

65 

6E 

74 

20 

6C 

6F 

61 

64 

65 

72 

20 

2E 

2E 

2E 

24 

01D2 

CD 

0A 

0D 

OA 

2E 

43 

aesl 

db 

cr,lf,cr,lf (’.COM  file  not  foundt’ 

4F 

4D 

20 

66 

69 

6C 

65 

20 

6E 

6F 

74 

20 
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66  6F  75  6E  64  24 
01EA  00  0A  00  0A  2 E  43 

■es2 

db 

cr»lf|Cr,lf( 

i ’ . C0H  file  loaded’, cr, If, '4' 

4F  40  20  bb  69  6C 

65  20  bC  bF  b  1  64 

65  64  00  0A  24 

0201  0000 

useg 

dH 

0 

=  0203 

0203 

cseg 

end of s 
ends 

equ  ( 

;  end  of  code  segment 

Open  procedures: 

end 

start 

;  end  of  asseably  —  start  addr  at  "start" 

BI6L0AD 


End  Listing  Two 
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OF  INTEREST 


Product  Codes 
for  Coded  Products 

Software  will  be  vended  like  gro¬ 
ceries  if  Softwareland  has  its  way.  Soft- 
wareland  urges  “software  vendors  to 
adopt  uniform  product  codes,  such  as 
the  grocery  industry  has  already  done.” 
Software  products  will  carry  Uniform 
Product  Codes  (UPCs)  —  those  familiar 
bar  codes  we  see  on  our  milk  cartons, 
candy  bars,  etc.  These  have  the  advan¬ 
tage  of  keeping  the  retailer  posted  on 
stock  movement  and  reduce  the  kinds 
of  errors  caused  by  a  cashier’s  incorrect 
number  entry.  Electronic  point-of-sale 
(POS)  systems  keep  track  of  inventory. 
Softwareland  is  aggressively  pursuing 
this  policy  in  mass  mailings  to  soft¬ 
ware  vendors,  whom  they  assist  by 
producing  free  camera-ready  copies  of 
the  UPC  bars  and  numbers.  For  their 
own  POS  systems,  Softwareland  uses 
magnetic  strip  readers  for  credit  card 
sales  which  automatically  check  a 
card’s  validity  by  telephone  communi¬ 
cation  with  the  issuing  bank.  Apart 
from  the  appropriateness  of  such  a 
scheme’s  onset  (now  that  we’re  getting 
so  close  to  1984),  I  wonder  if  they’ve 
thought  it  all  through.  Read  a  magnetic 
disk  product  with  an  electronic  bar 
scanner?  Won’t  that  affect  the  data? 
Softwareland  currently  has  stores  in 
Scottsdale,  Phoenix,  and  Mesa,  Arizo¬ 
na,  and  plans  to  open  one  per  month, 
starting  immediately,  with  several 
hundred  open  by  1986.  Reader  Ser¬ 
vice  No.  101. 


The  Robots  Are  Coming 

Robots  may  soon  be  as  common¬ 
place  in  homes  as  microcomputers. 
Androbot  announces  several  personal 
robots  that  entertain,  communicate, 
and  do  other  useful  things.  B.O.B. 
(Brains  on  Board)  has  an  8086  board 
and  3Mb  of  memory.  Infrared  sensors 
attract  it  to  people,  whom  it  follows, 
using  ultrasonics  to  avoid  objects  in 
its  way,  while  talking  in  a  vocabulary 
of  over  100  words  and  phrases.  B.O.B. 
can  carry  things  for  you,  or  pull  them 
around  in  its  optional  AndroWagon.  It 
can  fetch  a  beer  from  an  optional 
AndroFridge.  Through  its  Androbus 


system,  it  can  be  expanded,  as  well  as 
through  commercially  available  soft¬ 
ware  (which  is  created  by  the  user 
with  the  Androbot  Control  Language 
—  ACL).  To  program  B.O.B.  it  must 
first  be  attached  to  any  computer  or 
terminal  with  a  serial  port.  Ten  slots 
house  electronic  components  for  the 
operating  system  and  permit  addition¬ 
al  cartridges  and  plug-in  boards  for 
memory  and  CPU  expansion,  voice 
recognition,  text-to-speech  modules, 
etc.  While  I  haven’t  put  a  “TM”  next 
to  all  of  those  “Andro”  terms,  Andro¬ 
bot  has  carefully  trademarked  all  of 
them,  including  other  options  like  the 
AndroSentry  home  security  and  alarm 
package.  B.O.B.  is  36.5  inches  tall  and 
24  inches  wide,  weighing  42  pounds. 
It  runs  on  rechargeable  batteries  that 
permit  several  hours  between  charges, 
and  costs  $2995.  AndroWagon  is  $95. 

B.O.B.  has  a  little  sibling  called 
Topo,  with  fewer  capabilities  and  a 
lower  price  tag  —  only  $795. 

The  baby  of  the  family  is  F.R.E.D. 
(Friendly  Robot  Educational  Device), 
a  pint-sized  version  which  can  be  pro¬ 
grammatically  controlled,  or  with  a 
remote  infrared  controller.  Attach  a 
pen  to  F.R.E.D.  and  it  draws  on  paper. 
F.R.E.D.  comes  with  a  mini  Andro¬ 
Wagon  so  that  it  can  move  small  items 
about.  This  one  costs  under  $300. 

AndroMan  is  billed  as  the  “world’s 
first  real-life  three-dimensional  video- 
game  robot.  Use  it  with  Atari  VCS 
2600  or  compatible  machines.  The 
foot-high  miniaturized  Androbot  is 
controlled  by  joystick  with  a  remote 
infrared  signal  and  comes  with  game 
cartridge,  transmitter,  game  playing 
field,  and  game  pieces  imprinted  with 
coded  information.  Navigate  Andro¬ 
Man  through  an  obstacle  course  after 
beginning  play  on  screen.  Contact  with 
coded  game  pieces  triggers  further  in¬ 
teractions.  During  game  play,  Andro¬ 
Man  talks  to  players.  We  weren’t  told 
a  price  on  this  one,  but  it,  like  all  the 
others,  was  “designed  with  ‘expanda¬ 
bility  in  mind.’  ”  Reader  Service  No. 
103. 


PC  Ports,  Clocks,  and  RAM 

RAM+3  from  Seattle  Computer  is 
a  slot-saving,  multifunctional  card  for 
IBM  PC  and  XT  with  DOS  1.1  or  2.0. 


It  has  clock/calendar,  battery  backup, 
parallel  and  RS-232  serial  ports,  up  to 
25 6K  additional  RAM,  and  Flash  Disk 
drive  simulation  software.  Seattle  Soft¬ 
ware  claims  that  because  they  are  the 
original  developers  of  PC  DOS,  they 
are  experts  at  properly  implementing 
the  software,  which  reduces  runtime 
of  disk -intensive  programs  by  as  much 
as  80%.  A  nonexpandable  board  is 
$210,  while  a  version  with  sockets  but 
no  additional  memory  is  $320.  Adding 
64K  brings  the  price  to  $395 ;  128K  to 
$470;  192K  is  $545;  256K  is  $620; 
and  expansion  64K  chip  kits  are  $80. 
Reader  Service  No.  105. 


Dual -Port  Daisywheel 

The  Image  I  daisywheel  printer 
from  Primages  has  switch-selectable 
RS-232  and  Centronics  connections 
and  an  automatic  sheet  feeder.  It  prints 
at  45  cps  and  sells  for  under  $2000. 
Looks  good,  but  what  they  don’t  tell 
us  is  whether  it  offers  more  than  one 
pitch,  subscripts,  superscripts,  propor¬ 
tional  printing,  etc.  I  suspect  these  are 
included,  but  you’d  better  ask.  Reader 
Service  No.  107. 


A  Carryover 

Send  files  between  any  two  CP/M 
machines  that  can  be  physically  con¬ 
nected  ( including  Apple  CP/M )  (either 
by  RS-232  ports  or  by  two  modems) 
with  The  Transporter,  from  Workman 
and  Associates.  According  to  Workman, 
you  need  this  product  because  there  is 
no  way  an  8 -inch  drive  can  read  a  514- 
inch  drive,  and  there  are  no  standard 
514-inch  formats.  Even  two  machines 
with  the  same  physical  disk  require¬ 
ments  can’t  talk  to  each  other,  so  Kay- 
Pros  and  Osbornes  can’t  read  each 
other’s  disks.  The  Transporter  does 
not  have  to  be  installed,  nor  do  you 
need  different  copies  for  each  comput¬ 
er.  It  sends  itself  and  then  can  send 
from  the  second  machine.  It  sends  to 
CP/M-86.  A  CP/M-86  sender  will 
soon  be  available.  $69.50. 
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Workman  and  Associates  also 
offers  what  many  call  the  best  version 
of  C  for  the  price,  BDS  C,  at  lower 
than  list  —  $130.  This  version  of  C 
compiles  faster  than  most  (notably  the 
best-known  version  that  sells  for  over 
$500),  has  good  error  recovery,  and 
generates  tight  code.  While  it  is  not 
“full”  version  7  compatible  C,  lacking 
enumeration  types  and  explicit  reals, 
“most  everything  works  a  la  Kernighan 
and  Ritchie.”  A  reals  package  is  in¬ 
cluded  as  an  addendum.  Add  $10  for 
the  standard  Kernighan  and  Ritchie 
text  and  $15  for  a  disk  of  example 
programs,  including  games,  CP/M  low- 
level  utilities,  a  file  listing  program, 
and  the  SQ/USQ  file  compacting  pro¬ 
grams.  Updates  cost  $35  for  those  who 
have  earlier  versions  than  1.50  of  BDS 
C.  Return  the  original  disk  and  get  it 
and  two  new  disks  back  (one  with  de¬ 
bugger).  Reader  Service  No.  109. 


Your  Pal  SAL 

SAL/80  and  SAL/86  by  Protools 
are  Structured  Assembly  Language 
compilers  that  compare  to  C  or  Pascal 
in  emitting  optimally  dense  test/branch 
code  for  a  vocabulary  of  control  struc¬ 
tures.  I/O  primitives  permit  complex, 
user-friendly  interfaces  to  a  level  com¬ 
parable  to  BASIC.  A  compiler  toggle 
enforces  optimal  use  of  Z80  instruc¬ 
tions.  While  SAL  currently  supports 
Intel  mnemonics,  Z80  is  coming  soon 
in  an  update.  Protools  describe  this  as 
the  ideal  tool  for  engineers  and  pro¬ 
grammers  who  want  to  cut  develop¬ 
ment  costs  in  half  and  reduce  mainte¬ 
nance  costs  by  90%.  You  need  CP/M, 
MAC/RMAC,  64K,  at  least  140K  disk 
space,  and  $100.  Reader  Service  No. 
Ill. 


What's  a  VIXEL? 

VIXELs  are  a  series  of  $12.95 
tape  packages  from  The  Code  Works 
for  the  VIC-20,  most  of  which  work 
on  the  unexpanded  machine.  Among 
the  games  are:  Fire,  a  helicopter- 
putting-out-fires  game;  Draw,  a  high- 
res  sketchpad  program;  and  Race,  a 
“smash-em-up”  game  of  chicken. 
Another  game  is  called  Warp,  which 

simulates  the  feeling  of  flying  in  a 
spaceship  through  a  hyperspace  tunnel 
(requires  joystick). 

The  Code  Works  also  offers  Cursor 
64,  $12.95  tape  packages  for  the  Com¬ 
modore  64.  Among  the  games  in  this 
package  are:  Fifteen,  Safe,  wherein 


you  must  open  a  safe  with  rotating 
combination  lock  before  the  cops 
come  to  get  you;  and  Piano,  with 
a  keyboard  and  a  bouncing  dot  (a 
sprite)  which  shows  the  keys  being 
pressed,  and  comes  complete  with 
three  tunes  and  instructions  for  adding 
more  of  your  own.  Add  $1  per  order 
for  postage  and  handling;  Californians 
add  6%  sales  tax.  Reader  Service  No. 
113. 


Indecipherable  Software 

Dedicate/32,  from  Merritt  Soft¬ 
ware,  is  RSA  (Rivest  Shamir  Adleman) 
based  public  key  encryption  software 
for  Z80  CP/M  or  MP/M  microcomput¬ 
ers.  It  can  be  used  by  businessmen  to 
protect  payroll  and  client  records, 
electronic  mail  subscribers,  security 
managers,  programming  departments 
to  avoid  disclosure  of  development 
paths,  bankers  wishing  to  protect 
EFT,  and  companies  transmitting  con¬ 
fidential  information  to  branch  offices. 
The  public  key  system  is  RSA  type, 
modulus  size  256,  with  an  encryption 
time  of  33  seconds,  and  totally  ran¬ 
dom  and  unpredictable  key  generation 
produced  in  under  15  minutes.  This 
company  claims  that  Dedicate/32  de¬ 
stroys  the  “myth”  that  there  is  no 
such  thing  as  a  truly  random  number 
(theirs  is  generated  by  disk  latency  and 
Z80  refresh  counter).  The  single  key 
system  is  type  PKS  Chaos  Engine  A-81, 
key  size  255  bytes,  with  a  speed  of 
9600  baud,  and  a  block  size  of  256 
bytes.  The  integrated  system  encodes 
any  CP/M  file  with  the  output  able  to 
be  sent  by  any  communications  sys¬ 
tem.  The  public  key  technique  means 
never  having  to  reveal  your  decrypting 
key,  for  extra  security.  Merritt  claims 
Dedicate/32  is  uncrackable.  I  wonder 
if  they  warranty  any  financial  losses 
occasioned  by  data  loss  if  the  code  is 
ever  cracked?  $175  plus  $5  (surface 
shipping)  or  $6  (air  shipping).  Reader 
Service  No.  115. 


A  Program  for  16  Computers 

Hobbyscoop  (pronounced  “Hob- 
byscope”)  started  as  a  Dutch  concept. 
Originally  for  four  computers,  each 
week  software  was  broadcast  for  a 
different  computer  in  a  form  that 
could  be  input  to  the  tape  interface. 
The  interfaces  were  too  slow  for  two 
of  the  machines,  necessitating  eight 
minutes  at  a  time  of  horrible  on-the- 
air  noises.  The  interfaces  were  not 


reliable;  and,  consequently,  the  inter¬ 
ests  of  more  computer  enthusiasts 
were  aroused.  This  led  to  the  develop¬ 
ment  of  NOS-BASICODE,  a  language 
which  can  be  read  by  over  16  comput¬ 
ers.  You  order  a  handbook  explaining 
NOS-BASICODE,  and  a  cassette  (read¬ 
able  by  any  of  the  current  group  of 
computers)  that  “teaches”  BASICODE 
to  your  computer  through  a  translation 
program.  Through  an  international 
radio  network,  the  Dutch-and-English 
broadcast  of  this  material  can  be  heard 
throughout  much  of  the  world.  Com¬ 
puters  which  are  capable  of  reading 
NOS-BASICODE  are  Apple,  BBC 
microcomputers,  all  Commodore 
computers  (including  PET  and  VIC), 
CP/M  computers,  DAI,  Exidy  Sorcerer, 
Heath  Zenith,  OSI  Challenger,  Philips 
P2000,  SWTPC-6800,  and  TRS-80 
Model  I  and  III.  You  can  pay  in  two 
ways:  either  transfer  the  amount  by 
the  Postgiro  system  to  account  num¬ 
ber  1419  in  Hilversum,  or  send  an  in¬ 
ternational  money  order  (IMO)  for  the 
exact  amount  payable  to  “Nos  Alge- 
meen  Secretariaat.”  In  both  cases, 
payment  must  be  in  Dutch  guilders. 
Prices,  all  in  Dutch  guilders,  are:  The 
Netherlands,  25;  Europe,  30;  outside 
Europe  seamail,  30;  U.S.  and  Canada 
airmail,  35 ;  Republic  of  South  Africa 
airmail,  38;  Japan  airmail,  38;  Austra¬ 
lia  and  New  Zealand  airmail,  38.  Pay¬ 
ment  goes  to  BASICODE,  Adminis¬ 
trate  Algemeen  Secretariaat,  NOS, 

P.  O.  Box  10,  1200  JB  Hilversum,  The 
Netherlands.  Send  any  correspondence 
(English  or  Dutch)  regarding  BASI¬ 
CODE  in  general,  or  program  contribu¬ 
tions,  to  Hobbyscoop,  P.O.  Box  1200, 
Hilversum,  The  Netherlands.  Send  any 
inquiries  about  Radio  Netherland’s 
English  service  or  regarding  the  “  Radio- 
Activity”  program  to  Jonathon  Marks, 
“Radio-Activity,”  Radio  Netherlands, 
Transcription  Service,  P.O.  Box  222, 
1200  JG  Hilversum,  The  Netherlands. 
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VERSA-FILE 

Company:  Analytic  Management  Sys¬ 
tems,  247  High  Street,  Palo  Alto,  CA 

94301 

Computer:  CP/M  2.2  or  greater,  and 

MP/M 

Price:  $69.00 

Circle  Reader  Service  No.  133 

Reviewed  by  Daniel  R.  Lunsford 

VERSA-FILE  is  a  small  data  file 
management  package  with  full-screen 
data  entry  and  display,  built-in  report 
generation,  sort  package,  and  other  main¬ 
tenance  utilities.  It  is  limited  in  scope;  for 
instance,  files  are  limited  to  four  charac¬ 
ter  keys  and  only  1000  records  per  file. 
Even  with  these  limitations,  however,  I 
found  it  did  what  I  wanted  with  reason¬ 
able  speed  and  no  discernible  bugs  (once 
I  got  it  up  and  running,  that  is  —  getting 
it  running  was  another  thing  altogether! ). 
My  overall  impression  is  that  of  a  good 
solid  program  that  does  what  it  was  de¬ 
signed  to  do.  It  won’t  do  everything,  but 
what  do  you  expect  for  $69? 

Operation  of  the  package  is  simpli¬ 
city  itself.  The  structure  of  each  file  is 
described  in  a  “schema”  file,  which  is 
prepared  with  a  standard  text  editor.  The 
schema  contains  the  name  of  each  field  in 
a  record,  its  attributes  (length,  datatype, 
where  on  the  screen  the  field  is  to  be  dis¬ 
played,  etc.),  and  the  prompts  that  will 
be  displayed  onscreen  during  an  entry 
session.  Once  this  is  prepared,  a  VERSA- 
FILE  utility  is  run,  which  creates  the 
indexes,  and  screen  formats,  and  displays 
the  actual  datafile.  Then  you  just  enter 
data.  It’s  completely  menu  driven,  and 
catches  most  data-entry  errors  as  well. 

The  system  includes  select  and  sort 
logic,  which  I  found  very  easy  and  natural 
to  use.  As  an  experiment,  I  created  a 
book -cataloging  schema  for  our  library, 
stuck  about  100  books  into  the  database, 
and  started  selecting  and  sorting  for  vari¬ 
ous  criteria;  it  performed  flawlessly  each 
time.  The  limitations  are  within  reason 
for  a  package  of  this  size  and  price  range; 
the  sort,  for  instance,  is  an  in-memory 
variety  and  hence  cannot  handle  a  really 
big  file.  I  estimate  that  my  library  would 
need  at  least  five  VERSA-FILE  data  sets 
(I  have  a  large  library).  Again,  not  bad  for 
the  price. 

The  report  generator  facility  is  one 
of  the  simplest  and  best  I’ve  ever  seen.  I 
once  had  the  occasion  to  see  someone  use 
another  data  manager,  one  of  the  large 
$500+  ones,  and  getting  reports  out  of 
it  was  like  pulling  teeth.  VERSA-FILE, 
on  the  other  hand,  has  one  of  the  simplest 
report  generators  I’ve  seen  in  a  long  time, 
and  the  best  thing  is  that  it  works.  The 
operator  prepares  a  Forms  Definition  file, 
again  using  a  standard  text  editor,  that 
defines  exactly  where  on  the  printed  page 


the  data  are  to  be  put.  This  process  is  so 
easy  that  it’s  almost  insulting.  Titles, 
strings  of  characters  to  be  inserted,  and 
other  formatting  information  go  into 
this  file,  which  is  then  used  by  VERSA- 
FILE  to  generate  the  final  product.  An 
interesting  aspect  of  this  report  generator 
is  that  it  can  also  be  used  to  produce  files 
of  the  data  in  your  data  set.  These  can  be 
used  as  input  to  other  programs  such  as 
MBASIC  or  WordStar/MailMerge,  and 
vice  versa.  Very  useful. 

The  problems  I  encountered  were 
few,  but  one  was  major.  The  VERSA- 
FILE  system  relies  heavily  on  full-screen 
formatting  capability,  and  so  must  be 
modified  for  whatever  cursor  positioning 
protocol  your  system  requires.  The  sup¬ 
plied  installation  program  simply  did  not 
work.  I  have  an  HI 9,  which  is  one  of  the 
terminals  that  is  included  on  the  installa¬ 
tion  menu,  but  I  couldn’t  make  the  pro¬ 
gram  believe  me.  I  tried  installing  it  as  a 
custom  terminal,  and  it  still  wouldn’t 
take  it.  I  finally  did  a  file  comparison  on 
the  kernal  file,  before  and  after  installa¬ 
tion,  and  there  was  no  difference!  I  had 
to  go  in  with  ZSID,  find  the  area  where 
the  cursor  positioning  strings  were  kept, 
and  patch  them.  Since  this  program  is 
evidently  written  in  PL/ 1-80,  this  was  not 
a  trivial  undertaking.  My  system  is  a  stan¬ 
dard  CP/M  2.2,  and  I’ve  never  had  this 
kind  of  problem  before,  so  I  think  I’m 
justified  in  laying  this  at  AMS’s  feet. 

The  second  complaint  I  have  about 
VERSA-FILE  is  minor.  The  program  is 
menu-driven,  so  you  switch  modes  a  lot. 
At  each  step,  the  program  asks  you  which 
datafile  you  wish  to  operate  on.  This  is 
very  annoying,  and  should  be  eliminated. 
A  command  such  as  dBASE  II’s  USE, 
which  specifies  a  default  data  set,  would 
be  a  vast  improvement. 

All  in  all,  VERSA-FILE  is  a  remarka¬ 
bly  powerful  program,  and  should  be  con¬ 
sidered  by  anyone  needing  a  small  data 
file  management  system.  It’s  a  no-frills 
package  that  can  do  a  job  reliably,  and  it 
has  some  bells  and  whistles  that  I’ve  here¬ 
tofore  seen  only  in  packages  costing 
much  more.  For  the  price,  you  can’t  beat 
it.  This  is  really  an  excellent  example  of 
the  newest  trend  in  the  marketplace: 
good  quality,  low-cost  software. 


Dr.  Dobb’s  Journal,  November  1983 

714 


#86  December  1983 


$2.95  [$3.50  in  Canada] 


or  Users  of  Small  Computer  Systems 


Faster  Circles 
For  Apples 

n’s 
ital 

lagnostic 
Diskette 


r  Control 
umb 
inals 


Publisher  -  Jane  Nissen  Laidley 
Editor  -  Reynold  Wiggins 
Managing  Editor  -  Craig  LaGrow 
Contributing  Editors  - 

Robert  Blum,  Dave  Cortesi, 

Ray  Duncan,  Anthony  Skjellum, 
Michael  Wiesenberg 
Marketing  Director  —  Beatrice  Blatteis 
Marketing  Assistant  -  Sally  Brenton 
Marketing  Coordinator  —  Ed  Gueble 
Advertising  Director  -  Beatrice  Blatteis 
Advertising  Sales  — 

Alice  Hinton,  Walter  Andrzej  ewski 
Circulation  Director  -  Terri  Pond 
Circulation  Assistant  —  Billie  Greenwood 
Production  Manager  -  Barbara  Ruzgerian 
Production  Assistants  - 

Shelley  Rae  Doeden,  Alida  Hinton, 
Tom  Martin 

Typesetter  -  Paula  Fairchild 
Cover  -  Alida  Hinton 


Copyright  ©  1983  by  People’s  Computer 
Company  unless  otherwise  noted  on  specific 
articles.  All  rights  reserved. 

Subscription  Rates:  $2  5  per  year  within  the 
United  States;  $44  for  first  class  to  Canada 
and  Mexico;  $62  for  airmail  to  other  coun¬ 
tries.  Payment  must  be  in  U.S.  Dollars, 
drawn  on  a  U.S.  Bank. 

Writer’s  Guidelines:  All  items  should  be 
typed,  double-spaced  on  white  paper.  List¬ 
ings  should  be  produced  by  the  computer, 
using  a  fresh,  dark  ribbon  on  continuous 
white  paper.  Please  avoid  printing  on  perfo¬ 
rations.  Payment  is  in  contributor’s  copies. 
Requests  to  review  galleys  must  accompany 
the  manuscript  when  it  is  first  submitted. 
Authors  may  receive  a  copy  of  the  complete 
writer’s  guidelines  by  sending  a  self- 
addressed,  stamped  envelope. 

Donating  Subscribers  Contributing  Sub¬ 
scriber:  $  50/year  ($25  tax  deductible).  Re¬ 
taining  Subscriber:  $7 5/year  ($50  tax  de¬ 
ductible).  Sustaining  Subscriber:  $  100/year 
($75  tax  deductible).  Lifetime  Subscriber: 
$1000  ($800  tax  deductible).  Corporate 
Subscriber:  $  500/year  ($400  tax  deductible, 
receives  five  one -year  subscriptions). 

Contributing  Subscribers:  Christine  Bell, 
W.  D.  Rausch,  DeWitt  S.  Brown,  Burks  A. 
Smith,  Robert  C.  Luckey,  Transdata  Corp., 
Mark  Ketter,  John  W.  Campbell,  Friden 
Mailing  Equipment,  Frank  Lawyer,  Rodney 
Black,  Thomas  Davis,  Kenneth  Drexler,  Real 
Paquin,  Ed  Malin,  John  Saylor,  Jr.,  Ted  A. 
Reuss  III,  Infoworld,  Stan  Veit,  Western  Ma¬ 
terial  Control,  S.  P.  Kennedy,  John  Hatch, 
Richard  Jorgensen,  John  Boak.  Lifetime 
Subscriber:  Michael  S.  Zick. 

Foreign  Distributors  UK  &  Europe: 

Homecomputer  Vertriebs  HMBH  282,  Flu- 
gelstr.  47,  4000  Dusseldorf  1,  West  Germany; 
La  Nacelle  Bookstore,  Procedure  D’Abonne- 
ment  1-74,  2,  Rue  Campagne  -  Premiere, 
F-75014  Paris,  France ;  Computercollectief, 
Amstel  312A,  1017  AP  Amsterdam,  Nether¬ 
lands.  Asia  &  Australia:  ASCII  Publishing, 
Inc.,  4F  Segawa  Bldg.  5-2-2,  Jingumae, 
Shibuya-Ku,  Tokyo  150,  Japan ;  Computer 
Services,  P.O.  Box  13,  Clayfield  QLD  4011, 
Australia;  Computer  Store,  P.O.  Box  31-261, 
22B  Milford  Rd.,  Milford,  Auckland  9,  New 
Zealand.  ( Write  for  Canadian  distributors) 


Dr.  Dobb’s  Journal,  December  1983 
716 


Dr.  Dobb's  Journal 

For  Users  of  Small  Computer  Systems 


December  1983 
Volume  8,  Issue  12 


CONTENTS 


ARTICLES 

18  Faster  Circles  for  Apples 

by  Myron  L.  Pulier 

Inspired  by  Daniel  Lee’s  “Fast  Circle  Routine”  (May  1983  DDJ,  No.  79),  these 
circle-generation  programs  use  Applesoft  BASIC  and  assembly  language  to  provide 
greater  speed  for  Apple  users.  Two  other  DDJ  readers  also  submit  their  amplifica¬ 
tions  on  Lee’s  algorithm. 

32  Cursor  Control  for  Dumb  Terminals 

by  Ian  Ashdown 

Want  to  teach  your  “antique”  terminal  to  do  direct  cursor  addressing?  This  author 
has  developed  a  conversion  program  that’s  easy  to  implement  on  your  CP/M  system. 

40  Dysan's  Digital  Diagnostic  Diskette 

by  Loren  Amelang 

Tired  of  paying  someone  else  a  bundle  of  money  to  analyze  and  repair  your  faulty 
disk  drive?  Let  this  author  show  you  how  a  program  and  Dysan’s  DDD  can  help 
you  make  your  own  diagnoses,  without  an  oscilloscope  or  other  fancy  equipment. 

80  Building  a  Programmable  Frequency  Synthesizer 

by  Michael  L.  Simon 

Here’s  how  one  author  used  a  phase-locked  loop  to  create  a  programmable  fre¬ 
quency  synthesizer.  Using  a  spare  counter/timer  channel  on  a  single-board  com¬ 
puter,  the  configuration  can  multiply  frequencies  exactly. 

DEPARTMENTS 

9  Editorial 
9  Letters 

12  Dr.  Dobb's  Clinic 

A  brief  look  at  two  new  computer  columnists 

14  C/Unix  Programmer's  Notebook 

How  Unix -type  environments  can  lead  to  non -interactive  and  user-unfriendly 
software 

92  CP/M  Exchange 

Solutions  to  interfacing  a  hard  disk  within  a  CP/M  environment,  and  how  to 
speed  up  SUBMIT  file  truncation 

102  16-Bit  Software  Toolbox 

A  look  at  the  new  MS-DOS  EXEC  function  —  a  powerful  “Unix-like”  modifi¬ 
cation  which  should  work  well  in  a  multi-tasking  environment 

112  Software  Reviews 
1 16  Book  Reviews 
120  Of  Interest 


Dr.  Dobb's  Journal  (USPS  307690)  is  published  twelve  times  per  year  by  People’s  Computer 
Company,  P.O.  Box  E,  Menlo  Park,  CA  94026.  Second  class  postage  paid  at  Menlo  Park,  California 
94026  and  additional  entry  points.  Address  correction  requested.  Postmaster:  send  form  3579  to 
People’s  Computer  Company,  Box  E,  Menlo  Park,  CA  94026  •  415/323-3111  ISSN  0278-6508 


5 


LETTERS  ' 


Augusta  Q  &  A 

Dear  DDJ : 

Edward  Mitchell’s  four-part  series  on 
his  Augusta  compiler,  concluded  in  the  Ju¬ 
ly  1983  issue,  was  certainly  interesting. The 
sheer  magnitude  of  effort  that  he  put  into 
it  is  mind-boggling.  It  was  definitely  a  plus 
that  he  gave  a  detailed  description  of  his 
program,  rather  than  just  a  long  listing. 

But  I  find  myself  baffled  by  his  pen¬ 
chant  for  doing  things  the  hard  way.  He 
rightly  points  out  that  BASIC  is  a  less  than 
ideal  language  for  compiler  writing.  OK, 
he  couldn’t  find  a  version  of  Pascal,  C,  or 
Forth  to  run  on  his  Osborne.  (Really??) 
But  since  he’s  obviously  interested  in 
systems  programming,  why  on  earth  use 
an  Osborne? 

Along  the  same  lines,  one  wonders 
why  he  chose  to  use  a  recursive  descent 
parser.  When  coded  in  a  language  that 
permits  recursive  subroutine  calls,  one 
can  write  such  a  parser  simply,  rapidly, 
and  bug-free.  But  BASIC  permits  no  such 
thing.  Since  he  had  to  go  to  the  trouble 
of  maintaining  a  push-down  stack  to 
simulate  recursion,  why  not  write  an  aug¬ 
mented  push-down  machine  parser?  (See 
P.  M.  Lewis  II,  D.  J.  Rosenkrantz,  and 
R.  E.  Stearns,  Compiler  Design  Theory, 
Addison -Wesley,  1976.)  Such  an  algo¬ 
rithm  requires  maintaining  a  stack  of  only 
the  symbols  in  the  same  LL(1)  grammar 
used  for  recursive  descent  parsing.  Logi¬ 
cally,  the  two  algorithms  are  equivalent 
since  each  subroutine  call  in  recursive 
descent  corresponds  to  a  symbol  in  the 


grammar.  By  doing  “recursive  descent” 
in  BASIC,  he  is  saddled  with  stacking 
subroutine  calls  and  local  variables  — 
making  his  stack  larger  than  necessary 
when  memory  is  at  a  premium.  In  addition, 
the  additional  work  needed  to  simulate 
recursion  complicated  his  code  and  prob¬ 
ably  added  enormously  to  the  debugging 
time.  A  table-driven  augmented  push¬ 
down  machine  parser  would  have  been 
shorter  and  simpler. 

While  I’m  impressed  by  his  having 
actually  gotten  Augusta  up  and  running, 
it  seems  to  be  a  classic  example  of  an  un¬ 
necessarily  complicated  solution  to  a 
problem  resulting  from  choosing  the 
wrong  design  and  working  with  the  wrong 
tools.  I  wouldn’t  recommend  to  others  to 
follow  that  lead. 

Very  truly  yours, 

Clyde  B.  Schechter 
520  West  122  Street 
New  York,  NY  10027 


Reply  to  Clyde  Schechter: 

Clyde  Schechter  raises  some  questions 
that  other  readers  may  also  be  curious 
about  so  I’ll  try  to  respond  as  best  I  can. 

To  put  the  Augusta  project  in  proper 
perspective:  Augusta  was  begun  as  a  hob¬ 
byist  project.  That  means  it  was  done 
essentially  for  the  sake  of  doing  it,  in  the 
sense  that  rock  climbers  attempt  difficult 
climbs  solely  for  the  sake  of  the  climb. 

Obviously,  as  I  explained  in  Part  IV 
of  the  Augusta  series,  neither  BASIC  nor 


an  Osborne  I  was  the  ideal  development 
vehicle  for  a  large  software  project.  But 
in  view  of  the  hobbyist  nature  of  Augus¬ 
ta’s  development,  purchasing  a  “real” 
computer  was  out  of  the  question. 

Languages  other  than  BASIC  were 
available  for  the  Osborne  I.  But  due  to 
the  92K  disk  size  on  the  Osborne  I,  the 
other  languages  were  effectively  useless. 
At  least  one  of  the  languages  required 
almost  140K  for  the  compiler  alone.  That 
leaves  little  room  for  source  code.  And 
since  the  Augusta  compiler  had  yet  to  be 
written,  I  could  only  estimate  how  much 
disk  space  I  would  need  for  source  and 
object  modules. 

As  I  mulled  over  the  choices,  Micro¬ 
soft  BASIC  seemed  to  be  the  best,  a  small 
program  itself,  with  both  interactive  and 
compiled  versions  available.  In  addition, 
Tiny-Pascal,  a  project  similar  in  scope  to 
Augusta,  had  also  been  written  in  BASIC, 
so  I  knew  that  it  was  “do-able.”  In  fact, 
the  bulk  of  Augusta  was  written  in  about 
five  weeks,  working  only  part  time.  Once 
compiled  with  the  BASIC  compiler, 
Augusta  was  compiling  at  over  300  lines 
per  minute,  which  compares  quite  favora¬ 
bly  to  other  microcomputer  compilers. 
So  all  in  all,  it  really  wasn’t  that  difficult 
to  write  the  compiler  in  BASIC.  (The 
greatest  difficulties  were  with  the  p-code 
interpreter  which  required  several  months 
of  writing  and  tweaking.) 

Mr.  Schechter  correctly  observes  that 
it’s  relatively  easy  to  write  a  recursive 
descent  parser  in  a  language  that  permits 


EDITORIAL 


Here  at  DDJ,  as  we  reach  the  end  of  1983  and  look 
back  over  the  past  twelve  issues,  we  are  encouraged  by 
what  we  see.  The  number  of  pages  is  roughly  twice  what 
it  was  a  year  ago.  Circulation  has  increased  substantially. 
The  new  faces  that  have  appeared  in  the  columns  have 
brought  with  them  fresh  enthusiasm  and  perspectives.  The 
somewhat  altered  face  of  the  magazine  makes  it  a  bit  easier 
to  find  on  the  newsstands,  and  also  a  bit  more  readable. 
Our  group  of  technical  referees  has  been  expanded,  and 
authors  are  now  being  paid. 

In  the  midst  of  all  this  change,  we  have  fought  to  main¬ 
tain  our  focus.  Your  responses  to  our  recently  completed 
reader  survey  have  given  us  additional  insight  into  what  we 
are  doing  right  and  what  we  can  improve,  what  you  want 
and  what  you  are  doing.  Our  thanks  to  all  those  who 
responded. 


Also  helpful  throughout  the  year  has  been  the  Editorial 
Response  insert  card.  Please  continue  to  use  it  to  vote  for 
your  favorite  item  in  the  issue  or  to  drop  us  short  com¬ 
ments.  The  Doctor  is  never  too  busy  to  listen,  and  the 
postage  is  covered. 

As  we  leave  1983,  we  look  for  1984  to  be  one  of  the 
best  years  yet  for  DDJ.  All  of  us  here  are  rededicating 
ourselves  to  the  task  of  improving  the  Journal.  Our  thanks 
to  all  of  you  for  your  continuing  support.  We  wish  you  a 
happy  holiday  season,  and  look  forward  to  serving  you  in 
the  New  Year. 


Reynold  Wiggins 
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recursive  subroutine  calls.  Prior  to  writing 
Augusta  I  had  worked  on  both  a  recursive 
descent  parser  for  a  BASIC  interpreter 
(written  in  Pascal)  and  a  table-driven  LL 
parser  for  a  subset  of  Pascal  (written  in 
Simula).  Based  on  that  experience,  I  found 
recursive  descent  to  be  easier  to  work 
with.  In  addition,  table-driven  predictive 
parsers  are  more  difficult  to  implement  in 
a  one-pass  compiler,  and  a  one-pass  com¬ 
piler  was  an  important  design  goal. 

To  sum  up,  his  points  are  well  taken. 
Undoubtedly  it  could  have  been  done 
easier  with  a  different  set  of  tools.  How¬ 
ever,  the  overall  development  of  the 
Augusta  compiler  was  not  as  difficult  as 
some  may  imagine  it  to  be.  Further,  my 
plans  all  along  have  been  to  rewrite 
Augusta  in  itself.  Having  the  original  com¬ 
piler  as  a  model  simplifies  the  rewrite, 
since  the  new  compiler  is  also  based  on 
recursive  descent  parsing. 

As  of  this  writing,  most  of  Augusta 
has  been  rewritten  in  Augusta.  Unfortu¬ 


nately,  I  have  been  busy  with  other  proj¬ 
ects,  including  writing  Software  Building 
Blocks  for  the  IBM  PC  (Hayden,  1984), 
as  coauthor  of  Software  Publishing  Cor¬ 
poration’s  PFS:WRITE,  and  the  teaching 
of  a  college  summer  school  class.  I  will, 
however,  be  back  working  on  Augusta  in 
the  near  future. 

I  do  appreciate  everyone’s  com¬ 
ments,  critical  or  praiseworthy.  Thanks 
for  writing. 

Edward  Mitchell 

S-100  to  Winchester  Improved 

Dear  Editor, 

David  Cortesi  has  suggested  some 
changes  to  my  Winchester  interface  board 
(Dr.  Dobb’s  Journal.  October  1983)  which 
would  extend  the  range  of  CPU  clock 
frequencies  with  which  it  would  work.  As 
an  added  benefit,  the  use  and  adjustment 
of  the  one-shots  are  eliminated. 

Note  that  the  modified  schematic 
(Figure  1,  below)  includes  a  wait  state 


generator,  capable  of  generating  one  or 
two  wait  states,  either  of  which  may  be 
selected  by  appropriately  connecting  the 
jumper.  Detailed  information  about  wait 
state  generators  may  be  found  in  Chapter 

5  of  Interfacing  to  S/100-IEEE  696 
Microcomputers  by  Sol  Libes  and  Mark 
Garetz,  Osborne/McGraw-Hill,  1981.  If 
additional  wait  states  are  needed,  say  for 
an  8  MHz  microprocessor,  then  the  D- 
type  flip-flop  could  be  replaced  by  a  shift 
register.  Details  about  the  use  of  such  a 
device  are  to  be  found  in  the  same  book. 

Sincerely  yours, 

Oscar  Goldman,  Professor 
Mathematics  Department 
University  of  Pennsylvania 
Philadelphia,  PA  19104 

Recovering  Lost  WordStar  Text 

Dear  DDJ, 

Every  now  and  then,  for  various  rea¬ 
sons,  I  lose  what  I  have  just  typed  into 
WordStar.  This  induces  a  case  of  helpless 
rage.  It’s  not  the  retyping  I  mind,  it’s  the 
rethinking.  I  just  can’t  face  it. 

The  last  time  this  happened  to  me,  I 
didn’t  give  up.  WordStar  was  in  an  endless 
loop:  beeping  and  inserting  exclamation 
points  in  weird  and  what  would  otherwise 
be  fascinating  patterns.  The  keyboard  was 
dead.  Pulling  out  the  printer  interface 
card  while  the  machine  was  running  (not 
recommended!)  stopped  the  malignant 
activity,  but  the  keyboard  was  still  dead. 
Eventually,  there  was  nothing  for  it  but 
CTRL-RESET.  There  went  all  my  work. . . 

But,  wait.  Maybe  it’s  still  in  memory! 
I  called  up  DDT  and  used  the  D  command 
to  examine  all  of  memory,  from  the  be¬ 
ginning.  Sure  enough,  at  hex  7849  on, 
there  were  my  precious  words!  I  used  the 
DDT  M  command  to  move  my  text  to 
0100.  Back  to  the  system  with  CTRL-C. 
Save  the  recovered  material  (e.g.,  SAVE 

6  HOPE).  Not  only  can  it  be  typed 
(TYPE  HOPE),  but  I  could  use  it  as  input 
to  WordStar  with  no  problems!  (Well, 
there  was  garbage  at  the  end,  a  small  price 
to  pay,  and  no  doubt  inserting  a  proper 
terminator  with  DDT  would  have  cured 
that.) 

Too  late  to  recover  that  three-page 
letter  I  wrote  a  month  ago  —  but  I’m 
ready  for  next  time.  Don’t  wait  until  it 
happens  to  you.  Practice  now.  Be  pre¬ 
pared  ! 

Keith  K.  Davison 
239  Clinton  Road 
Brookline,  MA  02146 

More  Circles  and  Such 

We  received  several  items  amplifying  the 
circle  generation  discussion  begun  by 
Daniel  Lee  in  the  May  1983  DDJ.  In  or¬ 
der  to  present  them  all  together,  this 
month  the  Letters  column  spills  over 
to  the  sidebars  on  pages  14-16.  -  Ed. 
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Figure  1. 

The  improved  circuit  diagram. 
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by  D.  E.  Cortesi,  Resident  Intern 


Readers  of  this  column  should  know 
about  two  recent  startups  in  the  column 
industry.  The  first  is  a  big-time  effort 
that,  we  think,  faces  grave  difficulties. 
The  second  promises  to  be  a  gem  of  great 
value  and  deserves  to  be  widely  read. 

Big-Time  Columnizing 

Many  of  you  will  already  know  that 
Douglas  Hofstader  has  retired  his  “Meta- 
magical  Themas”  in  Scientific  American 
and  that  Brian  Hayes  has  stepped  into  that 
hallowed  space  (originally  occupied  by 
Martin  Gardner’s  “Mathematical  Games”) 
with  “Computer  Recreations.”  His  first 
effort,  a  consideration  of  the  fundamental 
shift  in  thinking  encouraged  by  spread¬ 
sheet  calculators,  appeared  in  the  October 
issue.  It’s  a  welcome  sign  when  the  august 
SciAm  recognizes  the  prevalence,  and  the 
fun,  of  personal  computing,  and  we  wish 
Hayes  the  best  of  luck. 

System -Dependent  Prose 

However,  columnizing  isn’t  easy  in 
the  best  of  circumstances,  and  he  faces 
some  difficulties.  We  wonder  how  (given 
the  magazine’s  huge  circulation,  the  diver¬ 
sity  of  its  readers’  interests,  and  the  diver¬ 
sity  of  the  computers  they  use)  he  is 
going  to  proceed.  Spreadsheets  are  safe 
enough  for  a  first  outing;  everybody  has 
one.  But  when  it  comes  time  to  present 
algorithms,  what  language  will  he  use? 
When  it  is  time  to  draw  a  graph,  can  he 
avoid  hardware  dependency? 

The  infernal,  niggling  differences 
between  one  language  (machine,  key¬ 
board,  disk  drive,  etc.  ad  nauseum)  are 
the  curse  of  computer  publishing,  and 
nobody  has  found  a  decent  way  to  pro¬ 


duce  system-independent  prose.  It  isn’t 
a  new  problem,  either.  The  Association 
for  Computing  Machinery  (ACM)  faced  it 
a  long  time  ago  and  decided  to  publish 
algorithms  in  “presentation  ALGOL,” 
the  ALGOL  syntax  augmented  with  a 
complicated  set  of  typographical  conven¬ 
tions.  Donald  Knuth  faced  it  and  opted 
to  design  his  own  CPU,  MIX,  and  to  pre¬ 
sent  algorithms  in  its  assembly  language, 
MIXAL.  These  solutions  are  essentially 
the  same.  They  proceed  from  the  assump¬ 
tions  that  (1)  no  two  readers  use  quite 
the  same  language,  and  (2)  each  reader 
knows  some  language  and  system  very 
well.  Therefore  all  readers  will  be  pre¬ 
sented  with  a  language  that  nobody 
knows  and  will  all  have  to  learn  it; 
afterward  they  can  translate  to  their  own 
environment. 

The  personal-computer  press  usually 
operates  on  the  theory  that  everybody 
knows  and  uses  some  form  of  BASIC,  and 
that  all  readers  are  good  enough  program¬ 
mers  to  convert  from  one  BASIC’s  idio- 
syncracies  to  those  of  their  own  machine’s 
BASIC.  It  isn’t  true,  of  course.  We  once 
published  a  program  for  the  IBM  PC  (in 
another  magazine)  and  later  received  a 
long  distance  call  from  an  unhappy  reader 
who  simply  couldn’t  understand  why  the 
program  didn’t  work  on  his  Victor  9000. 

Another  solution  is  to  embrace  the 
problem  and  publish  system -dependent 
material  only;  hence  we  have  magazines 
for  the  Apple,  the  Atari,  the  Color  Com¬ 
puter,  the  IBM  PC;  for  CP/M;  for  the 
Heathkit  product  line;  for  machines  that 
use  the  6502.  And  we  have  books  that 
appear  in  multiple  editions  with  only 
trifling  changes  in  their  content,  like  the 


series  of  The  Power  of  XXXXCalc  books. 
This  isn’t  a  solution  at  all,  of  course;  it 
only  hides  the  problem.  It  drives  up  costs, 
fragments  the  audiences,  and  prevents  the 
dissemination  of  good  solutions  to  many 
users. 

So  how  will  Hayes  handle  the  prob¬ 
lem?  Can  he  find  a  way  to  present  prob¬ 
lems  and  solutions  to  a  mass  audience  in  a 
way  that  will  be  interesting  and  useful  to 
most  of  his  readers?  We’ll  see. 

Bently's  Pearls 

Communications  of  the  ACM,  long¬ 
time  flagship  of  computer  science  journals, 
launched  a  new  column  in  its  August 
issue.  The  columnist  is  Jon  Bently,  an 
Associate  Professor  at  Carnegie-Mellon 
and  author  of  Writing  Efficient  Programs 
(a  book  that,  on  the  evidence  of  Bently’s 
debut  column,  we  certainly  plan  to  buy). 

The  column’s  title  is  “Programming 
Pearls,”  the  pearls  being  those  parts  of 
programs  whose  origination  require  “in¬ 
sight  and  craftsmanship.”  The  pearls  pre¬ 
sented  in  the  first  column  were  delightful 
and  gave  us  several  hours  of  vigorous, 
enjoyable  mental  exercise.  Bently  has 
avoided  the  problem  of  system  dependen¬ 
cy  by  keeping  his  problems  abstract  and 
by  presenting  algorithms  in  English  and, 
where  necessary,  in  a  simple  pseudo-code. 

Bently  plans  to  end  each  column 
with  questions  and  problems,  but  he  isn’t 
asking  for  solutions  from  his  readers 
(from  our  experience,  we’d  call  that  a 
mistake;  the  massed  mental  power  of  a 
motivated  readership  is  awesome).  Here  is 
one  of  the  problems  he  presented. 

“Rotate  a  vector  of  N  elements  by  I 
positions.  For  instance,  with  N=8  and 
7=3,  the  vector  A  BCDEFGH  is  rotated  to 
be  DEFGHABC.  It  is  easy  to  do  this  rota¬ 
tion  in  N  steps  if  we  have  available  an 
Af-element  intermediate  vector.  Can  you 
rotate  the  vector  in  time  proportional  to  N 
using  only  a  few  extra  words  of  storage?” 

We  could;  we  ended  up  using  five 
scratch  variables.  Furthermore,  when  we 
expressed  our  solution  as  a  BASIC  subrou¬ 
tine  (taking  variables  I  and  N  and  vector 
V  as  input,  modifying  the  contents  of  V ) , 
we  found  that  with  a  single  added  line  of 
code  we  could  accept  a  negative  value  of 
I  to  mean  “rotate  right.”  Can  you  find  a 
similar  pearl  for  this  oyster  of  Bently’s? 
If  you  enjoy  searching  for  that  one,  be 
sure  to  read  the  rest  of  his  column.  BBJ 
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C/UNIX  PROGRAMMER’S  NOTEBOOK 


by  Anthony  Skjellum 


In  the  last  column,  several  references 
to  the  book  The  C  Programming  Language 
and  its  authors  were  made.  Through  my 
error,  Brian  Kernighan’s  name  was  mis¬ 
spelled  consistently  throughout  the  col¬ 
umn.  I’m  sure  that  many  readers  noticed 
this  immediately.  Unfortunately,  I  didn’t 
until  I  saw  the  column  in  print.  [We  obvi¬ 
ously  missed  it  too.  Our  apologies.  -Ed.  ] 

In  this  second  Programmer’s  Note¬ 
book,  I’ll  discuss  how  Unix-type  environ¬ 
ments  can  lead  to  non-interactive,  and 
user-unfriendly,  software.  This  is  based 
on  experiences  I’ve  had  with  several  Unix 
and  Unix -like  systems  running  both  stan¬ 
dard  and  Berkeley  Unix. 

Skimming  through  the  ads  of  the 
October  DDJ,  I  noticed  a  very  interesting 
item:  the  Computer  Innovations  ad  con¬ 
cerning  the  soon-to-be-released  version 
of  their  C  compiler.  As  an  option,  this 
compiler  will  produce  programs/data 
exceeding  the  previous  limit  of  64K  seg¬ 
ments  imposed  by  all  8086  compilers  (C 
or  otherwise)  that  I’ve  seen.  Look  for  a 
review  in  this  column  early  next  year. 

Unix  Software 

The  Unix  operating  system  was  de¬ 
signed  to  reduce  repetition  of  program¬ 
ming  effort  by  permitting  modular  pro¬ 
grams  to  be  combined  via  pipes  and  tees. 
Since  input  and  output  are  redirectable 
under  Unix,  simple  programs  could  use 
console  input  and  output  for  one  applica¬ 
tion  and  be  used  as  part  of  a  pipeline  for 
another.  Thus,  unmodified  programs 
could  be  reharnessed  for  new  applications 
to  an  extent  not  possible  with  previous 
operating  systems. 

Pipes  and  input-output  redirection 
are  two  of  the  best  and  most  well-known 
features  of  the  Unix  system.  Microcom¬ 
puter  users  have  been  very  interested  in 
adding  these  capabilities  to  their  own 
operating  environments.  In  the  8 -bit 
world,  this  has  been  done  chiefly  through 
special  subroutine  libraries  such  as  “The 
Unica,”  or  in  C  runtime  packages.  For 
MS-DOS  2.0  users,  the  features  are  built 
into  the  operating  system. 

Despite  the  undisputed  usefulness  of 
pipelines  and  input-output  redirection, 
their  presence  in  Unix  has  lead  to  a  serious 
drawback  in  the  system’s  environment. 
This  drawback  is  the  proclivity  to  avoid 
interactive  programs  and  to  produce  user- 
unfriendly  software.  Furthermore,  the 
standard  Unix  console  interface  is  weaker 
than  under  other  operating  systems.  In 
the  remainder  of  this  column  I  will  discuss 


1.  Terse  (hard-to-remember)  program  names. 

2.  Lack  of  program  sign -on  and  sign-off  messages. 

3.  Lack  of  interactive  mode  to  alleviate  the  need  to  re-execute  a  program 
several  times  to  complete  a  set  of  operations. 

4.  Inconsistent  use  of  switch  (dash  options)  for  controlling  the  specifics  of 
program  execution. 

5.  Lack  of  descriptive  error  messages. 

6.  Cryptic,  incomplete,  and  erroneous  documentation. 

7.  Software  bugs:  undocumented  and  documented. 

8.  Cryptic  (or  missing)  internal  help  features. 

9.  Poor  console  interface  provided  by  Unix. 

10.  Lack  of  system  for  finding  program  names  by  the  function  required. 

Table  1 

Unix  Software  Problem  Areas 


$  fct  <  RETURN  > 

(activate  the  program  with  no  arguments) 

usage:  fct  -abcv  filel  . 

.fileN  (help  message) 

$ 

(shell  prompt ) 

Figure  1. 

Cryptic  fct  Session 

$  fct  <  RETURN  >  (activate  the  program  with  no  arguments) 

fct  (version  x.yz)  as  of  dd-mm-yy 
usage : 

fct  [dash  options]  filel  .  .  fileN 
dash  options: 

-a  perform  function  "a"  on  files  specified 

-b  perform  function  "b"  on  files  specified 

-c  perform  function  "c"  on  files  specified 

-v  verify  each  step  before  proceeding 

note:  -a  and  -b  are  mutually  exclusive;  -c  may  be  used  in  conjunction 
with  -b  only. 

End  of  execution. 

$  (shell  prompt) 

Figure  2. 

Friendly  fct  Session 
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these  weaknesses  as  I  perceive  them. 

Non  -  Interactive  Software 

Because  of  the  availability  of  pipes 
and  input-output  redirection,  many  Unix 
programs  are  designed  to  act  as  filters. 
Filters  are  programs  which  require  a  single 
sequential  input  data  stream  and  produce 
a  single  output  data  stream.  Such  pro¬ 
grams  are  suitable  as  pipe-fittings.  Because 
of  the  way  they  handle  data,  they  don’t 
normally  expect  to  be  used  interactively. 
In  most  cases  this  doesn’t  pose  a  problem 
for  users.  However,  because  such  programs 
do  not  expect  to  deal  directly  with 
humans,  but  only  with  input  and  output 
streams,  they  can  often  be  very  unfriendly 
in  handling  errors. 

The  problem  in  the  Unix  operating 
system  is  that  the  same  terse  philosophy 
applied  to  filters  also  pervades  most  of 
the  software  available.  This  includes  pro¬ 
grams  which  are  normally  executed  se¬ 
quentially  by  the  user  from  the  console. 
The  problems  come  in  several  areas  and 
some  of  these  problem  areas  are  listed  in 
Table  I  (page  14).  The  following  para¬ 
graphs  will  elaborate  each  of  the  points 
listed  in  that  table. 

Terse  Names 

Unix  program  names  are  usually  two 
or  three  letters  long  and  tend  to  be  cryp¬ 
tic.  While  this  saves  typing  for  experienced 
users,  it’s  frustrating  for  new  and  occa¬ 
sional  system  users.  Also,  since  the  Unix 
system  lacks  an  on-line  indexing  system 
for  finding  program  names  by  function, 
it’s  not  easy  to  find  the  right  program 
based  on  the  desired  function  alone. 

Sign-ons  and  Sign-offs 

Sign-on  and  sign-off  messages  are  a 
common  courtesy  in  the  computer  world. 
Virtually  all  standard  Unix  programs  lack 
these  two  simple  features.  While  this  is 
understandable  for  filters,  it  is  completely 
unnecessary  for  other  programs.  For  ex¬ 
ample,  if  two  versions  of  a  program  exist 
on  a  system,  the  only  easy  way  to  distin¬ 
guish  them  is  by  their  sign-on  messages. 

Besides  sign-ons/sign-offs,  it  is  also 
nice  for  a  program  to  give  progress  reports 
during  execution.  This  lets  the  user  know 
how  things  are  proceeding.  Standard  Unix 
software  doesn’t  normally  include  such  a 
feature. 

Internal  Help  Features 

Many  programs  include  a  feature 
summary  option  to  help  occasional  and 
new  users  remind  themselves  of  program 
operation.  Many  Unix  programs  also  have 
this  capability,  but  they  are  often  ex¬ 
tremely  cryptic  and  include  few  English 
words  to  supplement  the  sample  com¬ 
mand  line  which  they  display.  Figure  1 
(page  14)  displays  a  sample  session  in 
which  a  fictitious  program,  fct,  is  executed 


from  the  shell  with  no  arguments.  The 
program  responds  with  a  cryptic  help 
summary  typical  of  actual  Unix  com¬ 
mands.  In  Figure  2  (page  14)  the  same 
fct  program  session  is  presented,  but  this 
time  the  program  has  been  designed  to 
provide  a  user-friendly  help  feature  (and 
also  to  sign  on  and  off). 

Interactive  Modes 

Interactive  program  modes  provide  a 
friendly  environment  for  the  user.  When  a 
program  is  used  often,  it  may  be  executed 
several  times  consecutively.  An  interactive 
mode  eliminates  the  need  for  consecutive 
execution  since  the  user  can  enter  all  the 
commands  in  one  interactive  session.  This 
avoids  unnecessary  user  effort  and  is 
probably  more  efficient  from  a  system 
standpoint. 

One  reason  that  the  interactive  modes 
are  missing  is  the  lack  of  support  for  ex¬ 
panding  Unix  wildcard  filenames  from 
within  a  program.  I  find  this  limitation 
rather  arbitrary,  and  I  have  written  a  pro¬ 
gram  which  solves  the  problem  (see  “Ex¬ 
panding  Unix  Wildcards,”  DDJ,  No.  73, 
November  1982).  The  lack  of  direct  sup¬ 
port  for  such  a  function  indicates  that  the 
whole  Unix  philosophy  is  geared  towards 
non-interactive  software  tools. 

Command-line  Switches 

Unix  programs  use  command-line 
switches  (dash  options)  to  specify  the 
particulars  of  program  execution.  Switches 
usually  consist  of  a  dash  character  (“-”) 
followed  by  a  single  letter.  Unfortunately, 
Unix  programs  use  these  switches  incon¬ 
sistently.  For  example,  the  rm  command  al¬ 
lows  only  limited  positioning  of  switches, 
permitting  them  only  before  filenames  on 
the  command  line.  Some  programs  allow 
several  switches  to  be  combined  after  a 
single  dash  character  (e.g.,  -abcdef). 
Others  use  the  plus  (“+”)  character  to 
activate  a  program  feature  and  a  dash  to 
deactivate  it.  Generally,  it  is  difficult  to 
remember  all  the  different  possibilities, 
limitations,  and  defaults  imposed  by  the 
various  programs. 

The  difficulties  with  command-line 
switches  under  Unix  led  me  to  write  the 
ARGUM  package  which  was  published  in 
the  August  1982  issue  of  DDJ  (No.  70). 
That  article  proposed  a  program  which 
would  handle  switches  in  a  consistent 
way.  Existing  Unix  programs  could  be 
changed  to  use  ARGUM,  thus  eliminating 
one  degree  of  inconsistency  from  the 
operating  environment.  Alternatively,  the 
less  powerful  Unix  III  getopts()  facility 
could  be  used. 

Lack  of  Descriptive  Error  Messages 

The  lack  of  descriptive  error  messages 
is  a  real  problem,  especially  for  inexperi¬ 
enced  users.  One  offender  is  the  eqn/troff 
system  used  for  equation  and  text  photo¬ 


typesetting.  These  programs  report  errors 
as  “Syntax  Error”  between  two  line  num¬ 
bers.  They  don’t  echo  the  erroneous  text 
or  equation,  and  the  line  numbers  aren’t 
always  useful  because  header  files  change 
the  length  of  the  source  text. 

Another  problem  stems  from  the  way 
Unix  reports  failures.  Programs  which  at¬ 
tempt  to  open  a  file  and  fail  get  an  error 
code.  They  subsequently  report  the  failure 
as  “cannot  open  file.”  While  this  is  cor¬ 
rect,  it  doesn’t  tell  the  user  if  the  file  is 
nonexistent  or  if  a  file  protection  viola¬ 
tion  has  occurred.  Similarly,  when  users 
try  to  change  their  current  directory  to 
one  for  which  they  have  no  read  privileges, 
a  “bad  directory”  message  is  displayed 
by  the  Unix  shell. 


Documentation 

Documentation  is  a  real  problem  in 
the  Unix  system.  Most  programs  are 
documented  in  a  standard  form  which  is 
typically  very  terse.  The  examples  pro¬ 
vided  are  often  very  complicated  and 
don’t  clearly  illustrate  how  to  use  the 
program  for  simple  purposes.  Because  of 
the  poor  documentation,  some  casual 
users  think  of  Unix  systems  as  secret 
societies  since  only  the  indoctrinated  can 
tell  them  how  the  system  and  programs 
work. 

Another  problem  with  documenta¬ 
tion  is  that  it  sometimes  doesn’t  reflect 
the  current  state  of  a  program.  Most  nota¬ 
ble  on  the  system  I  use  are  undocumented 
features  of  the  standard  Unix  editor  ed. 
The  standard  form  provides  no  line  edit 
command  (“x”)  while  the  installed  ver¬ 
sion  does.  Yet,  the  documentation  does 
not  explain  this. 

Unix  documentation  is  clearly  the 
weak  link  in  the  system.  It  makes  some 
of  the  mysterious  concepts  of  the  system 
seem  impossible  to  grasp  and  reduces  pro¬ 
ductivity  through  its  terseness. 


Software  Bugs 

Another  problem  which  makes  a  Unix 
system  user-unfriendly  (actually  user- 
hostile)  is  the  presence  of  undocumented 
bugs  in  important  software  packages.  For 
example,  bugs  exist  in  the  eqn/troff  sys¬ 
tem.  These  can  be  circumvented,  but  the 
methods  are  known  only  to  a  few  experts. 
No  generally  available  documentation 
exists  for  avoiding  such  problems. 

Since  the  Unix  system  comes  with 
source  code,  it  should  be  feasible  for  indi¬ 
vidual  users  to  change  system  software  to 
their  specific  needs.  Unfortunately,  the 
source  code  which  accompanies  Unix  is 
mostly  comment-free  and  is  therefore 
difficult  to  understand  without  significant 
effort. 
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User  Console  Interface 

The  user  console  interface  is  not  ex¬ 
tremely  good  under  Unix.  For  example, 
when  a  character  is  deleted,  Unix  does 
not  actually  remove  the  character  typed 
but  just  moves  the  cursor  back  one  space. 
There  is  no  standard  mechanism  for  hav¬ 
ing  a  line  retyped,  and  backspacing  after 
typing  a  tab  doesn’t  produce  the  correct 
results.  Furthermore,  when  a  control 
character  is  typed,  it  is  displayed  in  the 
form  ACHAR,  but  when  deleted,  the  cur¬ 
sor  moves  back  only  one  space  (leaving 
the  caret). 

The  weak  user  interface  points  again 
to  the  philosophy  that  most  software  will 
not  be  interactive.  However,  the  standard 
Unix  editor  makes  no  attempt  to  improve 
the  interface  for  the  purpose  of  interactive 
editing.  It  is  so  unfriendly  that  most  users 
resort  to  other  editors  (usually  screen 
editors). 

Programmers  can  only  provide  their 
programs  with  a  superior  console  inter¬ 
face  by  using  the  raw  terminal  mode.  Un¬ 
fortunately,  this  mode  is  more  expensive 
in  terms  of  input-output  cost.  For  user- 
friendly,  screen-oriented  software,  it’s  the 
only  way  to  go. 


Conclusion 

Unix  is  a  powerful  operating  system, 
and  is  certainly  one  that  1  enjoy  using.  It 
does,  however,  have  a  number  of  user- 
unfriendly  aspects,  and  the  system 
philosophy  has  led  to  a  predilection  for 
non-interactive  software. 

1  look  forward  to  hearing  how  other 
Unix  users  perceive  the  Unix  environ¬ 
ment. 


■■J 
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Faster  Circles  for  Apples 


Daniel  Lee’s  article,  “Fast  Circle  Rou¬ 
tine,”  in  DDJ  No.  79  (May  1983) 
inspired  me  to  create  a  similar  circle¬ 
making  approach  for  the  Apple.  Although 
I  first  wrote  an  Applesoft  BASIC  program 
to  test  the  logic,  I  chose  variable  names 
that  could  serve  for  both  BASIC  and  as¬ 
sembly  language.  Thus  “X”  and  “Y”  refer 
to  the  X  and  Y  registers  of  the  Apple’s 
6502  chip,  and  “Xcrd”  and  “Ycrd”  are 
the  coordinates  for  the  points  of  the 
circle. 

A  circle  of  radius  R  centered  at 
(Xmid,  Ymid)  is  described  by  the  familiar 
formula 


by  Myron  L.  Pulier 


Myron  L.  Pulier,  M.D.,  101  Cedar  Lane, 
Teaneck,  New  Jersey  07666. 


(Ycrd-Ymid)A2 

+  (Xcrd -Xmid)  A  2  =  RA2 

where  Xcrd  is  the  horizontal  variable, 
Ycrd  is  the  vertical  variable,  and  Xmid 
and  Ymid  are  constants.  Differentiating 
with  respect  to  Xcrd  gives 

2  *( Ycrd -Ymid)  *d Ycrd /dXcrd 
+  2*  (Xcrd  -Xmid)  =  0 

whence 

dYcrd/dXcrd  = 

-  (Xmid -Xcrd)/ (Ymid -Ycrd) 

The  last  equation  implies  that,  in 
drawing  the  circle,  if  we  increase  Xcrd  by 
1  to  plot  the  next  point  we  must  decrease 
Ycrd  by 

(Xmid -Xcrd) /(Ymid -Ycrd) 

The  slowest  operation  here  is  division  by 
Ymid-Ycrd,  which  must  be  performed 
each  time  we  want  a  new  value  for  Ycrd. 


We  can  reduce  the  number  of  these  divi¬ 
sions  by  evaluating  the  expression  for 
only  one  eighth  of  the  circle  and  by  plot¬ 
ting  the  rest  of  the  circle  symmetrically 
about  the  coordinate  axes  and  about  a 
diagonal. 

It  is  best  to  select  the  upper  left  ex¬ 
treme  of  the  circle  as  the  starting  point. 
According  to  the  Apple  coordinate  sys¬ 
tem,  where  point  (0,0)  is  the  upper  left 
corner  of  the  screen,  our  starting  point  is 
given  by 

(Xmid-R/SQR(2),Ymid-R/SQR(2)) 

From  here  we  move  to  the  right  and  stop 
at  the  extreme  top  of  the  circle,  which  is 
point  (Xmid,Ymid-R).  This  choice  of 
starting  and  ending  points  facilitates  a 
simple  FOR-NEXT  program  loop  (FOR 
Xcrd  =  Xmid-R/SQR(2)  to  Xmid)  and 
avoids  the  divide-by-zero  error  we  might 
encounter  at  the  extreme  right  and  left  of 
the  circle,  where  the  slope  is  undefined. 


Reader  Commentary 

More  Fast  Circles  . . . 

Dear  DDJ, 

Daniel  L.  Lee’s  algorithm  has  got 
to  be  faster  than  Microsoft’s  pedestrian 
CIRCLE  command,  but  both  suffer 
from  the  same  malady:  they  reinvent 
the  wheel  —  only  this  time  it’s  square ! 

When  I  think  I’ve  discovered  a 
marvelous  algorithm,  I  wonder  if  I’ve 
outsmarted  the  professionals.  I  usually 
haven’t.  But  hope  springs  eternal.  I 
search  the  literature  anyway.  My 
brainchild  is  at  least  1 7  years  old  [  B. 
K.  P.  Horn,  “Circle  Generators  for 
Display  Devices,”  Computer  Graphics 
and  Image  Processing  (5),  pp.  280- 
288  (1976)]. 

Neither  trigonometry  nor  calculus 
is  needed  to  devise  a  circle  generator. 
For  a  circle  of  radius  R  one  wants  to 
plot  points  (X,Y)  with  integer  coordi¬ 
nates  which  most  nearly  solve  the 
equation 

X2  +  Y2  =  R2 

The  difference  between  the  left 
side  and  R2  is  a  measure  of  nearness. 
A  suitable  circle  generator  simply 
chooses  successive  points  to  minimize 
this  difference.  The  enclosed  listing 
(see  Listing  Three,  page  30)  is  a  ren¬ 
dering  of  such  an  algorithm.  It  gener¬ 
ates  points  for  about  one  eighth  of  the 


circle  and,  using  the  symmetry  of  the 
circle,  plots  eight  points  for  each  point 
generated.  For  use  with  digital  plotters, 
the  algorithm  is  invoked  eight  times 
forward  and  backward  so  that  the 
points  are  of  concentric  circles;  the 
low  algorithm  is  plotted  in  counter¬ 
clockwise  order.  I  enclose  a  plot  of 
concentric  circles  in  low  resolution  to 


exhibit  the  algorithm’s  behavior  (see 
Figure  2,  below). 

William  A.  McWorter,  Jr. 
Mathematics  Department 
Ohio  State  University 
23 1  W.  1 8th  Avenue 
Columbus,  OH  43210 

(Listing  Three  begins  on  page  30) 
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See  Figure  1  (at  right). 

For  each  point  that  we  find  by  the 
above  method,  we  can  generate  seven 
symmetric  points  by  reflection  through 
the  horizontal  and  vertical  diameters  of 
the  circle  and  by  exchanging  Xcrd  with 
Ycrd.  A  point  (Xcrd,Ycrd)  is  ABS(Xcrd- 
Xmid)  distant  from  the  vertical  axis  of 
the  circle.  Since  its  reflection  should  be 
the  same  distance  from  this  axis,  its  ab¬ 
scissa  is  2*Xmid-Xcrd.  Similarly,  reflec¬ 
tion  through  the  horizontal  diameter 
gives  an  ordinate  of  2*Ymid-Ycrd.  To 
reflect  a  point  through  the  diagonal  line 
that  runs  from  upper  left  to  lower  right, 
we  find  the  point  whose  distance  to  the 
vertical  axis  equals  the  distance  of  the 
original  point  to  the  horizontal  axis  and 
whose  distance  to  the  horizontal  axis  is 
the  same  as  the  original  point’s  distance 
from  the  vertical  axis,  namely 

(Xmid+Ymid-Ycrd,Xmid+Ymid-Xcrd) 

This  new  point  can  now  be  reflected  as 
before  through  the  vertical  and  horizontal 
axes. 

In  Listing  One  (page  21),  subroutine 
9000  plots  four  points  symmetrically 
about  the  horizontal  and  vertical  axes. 
Lines  10050  and  10055  switch  the  X  and 
Y  coordinates,  then  line  10060  calls  9000 
to  plot  the  four  new  points.  The  parame- 


Figure  1 . 

Faster  Circle 


Reader  Commentary 

. . .  And  Fast  Ellipses 

Dear  Sirs: 

Mr.  Daniel  Lee,  in  the  May  ’83 
issue,  presented  a  fast  circle  generator. 
It  compensated  for  any  given  screen 
aspect  ratio,  and  as  such  may  be  used 
as  an  ellipse  generator.  I  submit  the 
algorithm  described  below  as  an  even 
faster  alternative.  The  speed  improve¬ 
ment  results  from  the  elimination  of 
all  division  and  most  of  the  multiplica¬ 
tion.  The  approach  taken  could  easily 
be  modified  to  allow  the  generation 
of  arcs. 

The  method  which  I  present  here 
is  based  on  the  equation  of  the  circle, 
and  a  trick  which  eliminates  a  great 
deal  of  multiplication.  There  is  no 
calculus  or  trigonometry  involved,  im¬ 
plicitly  or  explictly. 

The  equation  of  the  circle  is  well 
known: 

x2  +  y2  =  r2  [  1 ] 

where  r  is  the  radius.  Since  we  want  to 
minimize  multiplication,  we  have  to 
use  “magic.”  A  magical  property  of 
the  positive  integers  is  that  the  square 
of  a  positive  integer  n  is  the  sum  of  the 
first  n  odd  numbers.  This  means  that  if 
we  want  to  compute  x2  for  each  x  we 
can  actually  plot  (i.e.,  each  integer  x), 
we  only  need  to  know  which  odd 


numbers  to  add  up.  The  same  applies 
to  y2. 

In  order  to  plot  a  circle,  we  might 
start  at  the  point  (0,r)  and  plot  towards 
(r,0),  using  symmetry  to  generate  the 
other  arcs  of  the  circle.  This  would 
mean  that  x  would  go  from  0  to  r,  y 
would  go  from  r  to  0,  x2  would  go 
from  0  to  r2,  and  y2  would  go  from  r2 
to  0.  It  is  easier  than  it  first  appears  to 
calculate  y2.  Note  that  y2  is  the  sum 
of  the  odd  numbers  from  1  to  2  y  - 1 .  In 
the  initialization  phase  it  will  be  neces¬ 
sary  (perhaps)  to  compute  y2  directly, 
but  for  y’  =  y  —  1 ,  y’2  =  y2  -  (2y- 1). 

Above  I  said  “perhaps”  because  it 
develops  that  one  does  not  need  to 
refer  directly  to  y2  or  even  to  x2.  The 
procedure  for  drawing  the  circle 
requires  that  we  assume,  as  we  did 
above,  that  we  will  draw  primarily 
from  (r,0)  to  (0,r)  and  use  symmetry 
to  generate  the  rest  of  the  points.  As 
we  compute  the  points  for  the  primary 
arc,  we  maintain  a  total  e.  The  total 
starts  at  0;  for  every  time  we  actually 
move  in  the  positive  x  direction,  we 
add  2x-  1  to  e;  for  every  time  we  actu¬ 
ally  move  in  the  negative  y  direction, 
we  subtract  2y-l  from  e.  We  decide 
precisely  which  step  or  combination  of 
steps  to  take  by  insisting  that  the  e 
that  would  result  from  the  step  or 
combination  of  steps  be  as  close  to  0 
as  possible. 


An  Ellipse 

To  generate  an  ellipse  is  a  slightly 
more  complex  matter,  but  in  the  end 
we  lose  little  speed.  The  equation  for 
an  ellipse  centered  at  the  origin  is 

b2x2  +  a2y2  =  a2b2  [2] 

where  b  is  the  positive  y-intercept,  a  is 
the  positive  x-intercept,  and  a/b  is  the 
resulting  aspect  ratio.  I  claim  that  in 
order  to  successfully  trace  the  ellipse 
we  need  only  do  exactly  as  we  do  for 
the  circle,  but  we  must  multiply  every 
reference  to  x  by  b2  and  every  refer¬ 
ence  to  y  by  a2.  In  other  words,  every 
time  we  actually  move  in  the  positive 
x  direction,  we  add  b2  ( 2x  - 1 )  toe;  for 
every  time  we  actually  move  in  the 
negative  y  direction,  we  must  subtract 
a2(2y-l)  from  e.  Again  we  decide 
which  step  or  combination  of  steps 
to  take  by  insisting  that  the  e  that 
would  result  from  the  step  or  combi¬ 
nation  of  steps  be  as  close  to  0  as 
possible.  In  this  case  we  are  plotting 
from  (0,b)  to  (a,0). 

If  perhaps  the  terms  b2(2x-l) 
and  a2(2y-l)  look  like  they  involve 
too  much  multiplication,  please  realize 
that  in  fact  no  multiplication  is  re¬ 
quired.  For  example,  we  would  already 
know  the  evaluation  of  b2(2x-l)  to 

(Continued  in  box  on  page  20} 
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ters  R2,  X2,  Y2,  and  XY  have  been  intro¬ 
duced  to  speed  computation. 

In  the  segment  of  the  circle  from  the 
upper  left  point  through  the  upper  mid¬ 
dle,  the  change  in  Ycrd  is  fractional  for 
each  unit  change  in  Xcrd.  Because  the 
Apple  plotting  routine  deals  with  integers, 
the  decrement  in  Ycrd  builds  until  it 
causes  the  line  being  drawn  to  move  up 
one  full  position. 

The  assembly  program  in  Listing 
Two  (page  22)  runs  much  faster  than  its 
Applesoft  equivalent.  Since  Xcrd  can 
range  from  0  through  279,  it  must  be  a 


double-precision  variable.  It  occupies  lo¬ 
cations  XCRDH  and  XCRDL.  Ycrd  is 
supplemented  by  a  fractional  portion 
stored  in  YCRDF.  Names  of  other  double¬ 
precision  integer  parameters  are  termi¬ 
nated  with  -H  or  -L  for  the  high-  and 
low-order  portions,  respectively.  Single- 
precision  assignment  is  indicated  in  the 
comments  by  while  double  preci¬ 

sion  is 

The  TEST  program  plots  a  circle  of 
radius  40  and  midpoint  (120,80).  It  ini¬ 
tializes  the  hires  screen  by  calling  TURN¬ 
ON.  The  subroutine  called  EIGHTH  per¬ 
forms  calculations  for  the  one- eighth 


circle.  Here  the  first  order  of  business  is 
to  approximate  the  value  of  R/SQR(2) 
by  using  R*3/4  instead.  Note  that  3/4 
in  decimal  is  1/2  +  1/4,  or  0.1  1  in  binary. 

The  next  lines  of  the  assembly  pro¬ 
gram  are  a  straightforward  translation  of 
their  Applesoft  equivalents.  Lines  75  and 
76  initialize  the  value  of  YCRDF  to  0. 
PLOTFOUR  is  called  in  lines  104  and  119 
to  place  four  points  symmetrically  about 
the  horizontal  and  vertical  axes  of  the 
circle.  PLOTFOUR  uses  the  Applesoft 
HPLOT  routine  to  perform  the  actual 
plotting.  HPLOT  requires  that  the  horizon¬ 
tal  coordinate  be  in  the  Y  and  X  registers, 


(Continued  from  page  19) 


be,  say,  ex.  To  determine  ex’  when 
x’ =  x  +  l,  note  that 

b2(2x’ -l)=b2[2(x  +  l)-ll 
=  b2(2x-l)  +  2b  , 

in  other  words, 

ex’=ex  +  2b2. 

A  similar  result  obtains  for  the  nega¬ 
tive  y  direction,  which  we  will  simply 
state: 

ey  * =  ey  —  2a2 . 

Algorithm  Summary 

To  summarize  the  algorithm:  start 
with  the  point  (0,b).  Initialize  e  to  0, 
ex  to  b2,  ey  to  2a2b-a2,  exy  to 
ex  +  ey.  Plot  the  current  point  and  cor¬ 
responding  points  in  the  other  quad¬ 
rants  of  the  ellipse.  Choose  the  next 
point  so  that  e  plus  ewhatever  is  mini¬ 
mized.  Set  e  according  to  that  choice, 
and  update  ex,  ey,  and  eXy.  When  the 
point  (a,0)  is  arrived  at,  the  ellipse  is 
complete. 

The  Listing 

The  program  shown  in  Listing 
Four  (page  30)  is  an  M BASIC  pro¬ 
gram  intended  to  interface  to  an  LSI 
ADM-3A  terminal.  Obviously,  if  speed 
is  a  concern,  BASIC  is  not  the  language 
of  choice.  I  chose  it  to  permit  the  pro¬ 
gram  to  be  tried  out  basically  anywhere, 
since  my  facilities  for  computer 
graphics  are  one-of-a-kind. 

Lines  1050-1240  are  the  routine 
itself.  The  point-plotting  routine  is  on 
lines  1310-1341. 

Caveat 

There  is  one  thing  that  the  imple¬ 
mentor  should  be  aware  of  before  he 
or  she  starts,  to  prevent  untraceable 
bugs.  The  formulae  for  ex ,  ey ,  and  exy 
include  squares  of  a  and  b.  These 
squares  accumulate  to  a  large  total 
rather  quickly.  The  solution  is  to  use  a 


wide  word  to  store  the  total,  and 
perhaps  (depending  on  the  size  of  your 
screen  in  pixels)  the  values  of  ex,  ey, 
and  exy  as  well. 

Drawing  Arcs 

The  method  can  be  modified 
to  draw  arcs  (see  Figure  3,  below) 
elliptical  or  otherwise,  with  careful 
initialization  and  a  well-considered 
termination  condition.  The  initializa¬ 
tion  involves  calculating  ex,  ey,  and 
exy  for  the  initial  point  of  the  arc  to 
be  drawn.  The  routine  should  terminate 
when  the  last  point  of  the  arc  is  drawn. 
The  actual  coordinates  of  the  final 
point  should  be  calculated  in  some 
fashion  that  allows  for  rational  num¬ 
bers,  and  then  a  point  with  integer 
coordinates  should  be  chosen  that 
approximates  the  actual  point.  This 
can  be  done  by  using  the  equation  of 
the  ellipse.  In  other  words,  the  best 
integer  approximation  (xi,yi)  of  the 
terminating  point  (x,y)  is  the  one  for 
which  (bxi)2  +  (ayi)2  is  closest  to 


(ab)2.  Again,  the  integer  coordinates 
of  the  final  point  should  be  computed 
in  the  initialization  phase  and  used  as 
the  termination  condition. 

Conclusion 

This  routine  can  draw  an  ellipse 
quickly,  using  no  multiplication  once 
initialized.  It  should  be  easily  imple¬ 
mented  in  68000  assembly  language, 
owing  to  that  processor’s  32-bit  register 
operations.  A  little  more  difficulty 
should  be  anticipated  by  users  of  the 
8086,  6809  or  Z80,  though  their 
16-bit  addition  capabilities  can  be 
»  used  to  advantage.  HLLs  can  speedily 
draw  circles  with  this  routine,  as  well, 
because  of  its  incremental  nature.  And 
finally,  the  algorithm  can  draw  arcs 
easily. 

Michael  T.  Enright 
2360  Hosp  Way,  #132 
Carlsbad,  C A  92008 

(Listing  Four  begins  on  page  30) 
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and  the  vertical  coordinate  in  the  A  regis¬ 
ter.  HPLOT  returns  these  coordinate 
values  at  the  zero-page  locations  named 
LASTHH,  LASTHL,  and  LASTV. 

The  division  sequence  starts  on  line 
135.  Since  the  divisor  and  dividend  are 
single  precision,  we  can  use  a  technique 
that  divides  a  one-byte  divisor  stored  in 
DIVISOR  into  a  one-byte  dividend  held 
in  the  A  register.  The  eight  shift  opera¬ 
tions  and  eight  subtractions  required  are 
counted  via  the  X  register.  The  result  of 
the  division  is  a  binary  fraction  generated 
in  QUOTIENT.  This  quotient  is  subtracted 
from  the  previous  value  of  YCRDF.  If  a 


borrow  is  required,  we  decrement  the 
integer  portion  of  Ycrd.  In  any  case,  Xcrd 
must  be  incremented  by  1  in  a  double¬ 
precision  operation.  The  FOR-NEXT 
loop  of  the  BASIC  version  is  implemented 
in  assembly  language  by  counting  the 
value  of  R2  down  through  zero,  since 
R/SQR(2)  points  will  be  plotted  for  one 
eighth  of  the  circle. 

Using  zero-page  locations  for  varia¬ 
bles  and  parameters  and  a  faster  division 
algorithm  will  increase  speed,  but  the  bot¬ 
tleneck  is  the  Applesoft  HPLOT  routine, 
which  maps  horizontal  and  vertical  co¬ 
ordinates  into  the  Apple  video  locations. 


Replacing  that  routine  with  a  table 
lookup  results  in  very  fast  circle  genera¬ 
tion. 

With  some  modification  the  “faster 
circle”  technique  can  produce  filled-in 
disks  or  wedges  for  pie  charts.  It  can  also 
rotate  and  translate  shapes  and  objects 
quickly  for  animation  effects. 


( Listings  begin  below) 


Circles  (Text  begins  on  page  18) 

Listing  One 


1 00® 

1005  Hgr 

1010  Hcolor  =  3 


£000  ************** TEST 

£005  R  =  40 
£010  XMID  =  1 £0 
£015  YMID  =  80 
£0£0  Gosub  10000 
£0£5  End 


9000  **************  PLOT FOUR 

9005  Hplot  H,  V 
9010  Hplot  X£  -  H,  V 
9015  Hplot  X£  -  H,  Y£  -  V 
90£0  Hplot  H,  Y£  -  V 
90£5  Ret  urn 


10050  V  -  XY  -  XCRD 

10055  H  =  XY  -  YCRD 

10060  Gosub  9000 

*  PLOT  4  POINTS 

10065  YCRD  =  YCRD  - 

(XMID  -  XCRD)  / 

(YMID  -  YCRD) 

10070  Next 
10075  Return 

END  OF  LISTING 

PROGRAM  LENGTH  =  4£1  BYTES, 

TOTAL  OF  31  LINE  NUMBERS 

£7  TOTAL  NON-REM  STATEMENTS, 

6  TOTAL  REMARKS 

END 

PR#0 


10000  *************  EIGHTH  End  Listing  One 

10005  R£  =  R  *  .7 
10010  YCRD  =  YMID  -  R£ 

10015  X£  =  XMID  +  XMID 
1 00£0  Y£  =  YMID  +  YMID 
100£5  XY  =  XMID  +  YMID 
10030  For  XCRD  =  XMID  -  R£  To  XMID 
10035  H  =  XCRD 

10040  V  =  YCRD 

10045  Gosub  9000 

t  PLOT  4  POINTS 
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Listing  Two 


0800 

3 

LST 

0800 

2C 

50 

C0 

4 

TURNON 

BIT 

GRAPHICS 

0803 

2C 

52 

C0 

5 

BIT 

FULL 

0808 

2C 

54 

C0 

6 

BIT 

PflGEl 

0809 

2C 

57 

C0 

7 

BIT 

HIRES 

080C 

fi9 

FF 

a 

LDfi 

#$FF 

080E 

85 

E4 

9 

STft 

HCQLOR 

0810 

ft9 

20 

10 

LDfl 

#$20 

0812 

85 

E6 

n 

STft 

HPflGE 

0814 

12 

5 

0814 

fi9 

28 

13 

TEST 

LDft 

#40 

; R  <-40 

0816 

8D 

2F 

09 

14 

STft 

R 

0819 

15 

5 

0819 

09 

78 

16 

LDft 

#120 

; XMID  <  <-120 

08  IB 

8D 

37 

09 

17 

STft 

XMIDL 

081 E 

09 

00 

18 

LDft 

#0 

0820 

8D 

36 

09 

19 

STft 

XMIDH 

0823 

20 

5 

0823 

09 

50 

21 

LDft 

#80 

; YMID <-80 

0825 

8D 

3C 

09 

22 

STft 

YMID 

0828 

23 

5 

0828 

20 

64 

08 

24 

JSR 

EIGHTH 

;DRflW  CIRCLE 

082B 

60 

25 

RTS 

082C 

26 

5 

082C 

OC 

2D 

09 

27 

PLOTFOUR 

LDY 

HH 

; HPLOT  H, V 

082F 

AE 

2E 

09 

28 

LDX 

HL 

0832 

ftD 

31 

09 

29 

LDft 

V 

0835 

20 

57 

F4 

30 

JSR 

HPLOT 

0838 

ftD 

33 

09 

31 

LDfi 

X2L 

; HPLOT  X2-H,  V 

083B 

38 

32 

SEC 

083C 

E5 

E0 

33 

SBC 

LftSTHL 

083E 

Oft 

34 

TAX 

083F 

ftD 

32 

09 

35 

LDft 

X2H 

0842 

E5 

El 

36 

SBC 

LftSTHH 

0844 

08 

37 

TOY 

0845 

ftD 

31 

09 

38 

LDfl 

V 

0848 

20 

57 

F4 

39 

JSR 

HPLOT 

084B 

04 

El 

40 

LDY 

LftSTHH 

; HPLOT  H2-H, Y2-V 

084D 

06 

E0 

41 

LDX 

LftSTHL 

084F 

ftD 

3B 

09 

42 

LDft 

Y2L 

0852 

38 

43 

SEC 

0853 

E5 

E2 

44 

SBC 

LflSTV 

0855 

20 

57 

F4 

45 

JSR 

HPLOT 

0858 

OC 

2D 

09 

46 

LDY 

HH 

085B 

ftE 

2E 

09 

47 

LDX 

HL 

085E 

05 

E2 

48 

LDft 

LflSTV 

0880 

20 

57 

F4 

49 

JSR 

HPLOT 

0863 

60 

50 

RTS 

0884 

51 

5 

0864 

ftD 

2F 

09 

52 

EIGHTH 

LDft 

R 

; R2  <  — R*3/4 

0867 

4fl 

53 

LSR 

0868 

18 

54 

CLC 

0869 

6D 

2F 

09 

55 

ADC 

R 

( Continued  on  page  24  ) 
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Circles  (Listing  continued,  text  begins  on  page  18) 

Listing  Two 


086C 

6A 

56 

0B6D 

8D 

30 

09 

57 

0870 

58 

0870 

AD 

3C 

09 

59 

0873 

AA 

60 

0874 

38 

61 

0875 

ED 

30 

09 

6£ 

0878 

8D 

3D 

09 

63 

087B 

64 

087B 

AD 

37 

09 

65 

087E 

0A 

66 

087F 

8D 

33 

09 

67 

088£ 

AD 

36 

09 

68 

0885 

2A 

69 

0886 

8D 

3£ 

09 

70 

0889 

71 

0889 

8A 

7  £ 

088A 

0A 

73 

088B 

8D 

3B 

09 

74 

088E 

A9 

00 

75 

0890 

8D 

3E 

09 

76 

0893 

£A 

77 

0894 

8D 

3A 

09 

78 

0897 

79 

0897 

8A 

80 

0898 

18 

81 

0899 

6D 

37 

09 

Q£ 

089C 

8D 

39 

09 

83 

089F 

A9 

00 

84 

08A1 

6D 

36 

09 

85 

08A4 

8D 

38 

09 

86 

08A7 

87 

08A7 

AD 

37 

09 

88 

08AA 

38 

89 

08AB 

ED 

30 

09 

90 

08AE 

8D 

35 

09 

91 

08B1 

AD 

36 

09 

9£ 

08B4 

E9 

00 

93 

08B6 

8D 

34 

09 

94 

08B9 

95 

08B9 

AD 

35 

09 

96 

08BC 

8D 

£E 

09 

97 

0SBF 

AD 

34 

09 

98 

0SC£ 

8D 

£D 

09 

99 

08C5 

100 

0SC5 

AD 

3D 

09 

101 

08C8 

8D 

31 

09 

10£ 

08CB 

103 

08CB 

£0 

£C 

08 

104 

08CE 

105 

08CE 

AD 

39 

09 

106 

08D1 

38 

107 

08D£ 

ED 

3D 

09 

108 

ROR 

STA  R£ 

5 

LDA  YMID 

TAX 

SEC 

SBC  R£ 

STA  YCRD 

■ 

LDA  XMIDL 
ASL 

STA  X£L 
LDA  XMIDH 
ROL 

STA  X£H 

■ 

TXA 

ASL 

STA  Y£L 
LDA  #0 
STA  YCRDF 
ROL 

STA  Y£H 

TXA 

CLC 

ADC  XMIDL 
STA  XYL 
LDA  #0 
ADC  XMIDH 
STA  XYH 

LDA  XMIDL 
SEC 

SBC  R£ 

STA  XCRDL 
LDA  XMIDH 
SBC  #0 
STA  XCRDH 

■ 

NXPOINT  LDA  XCRDL 
STA  HL 
LDA  XCRDH 
STA  HH 

LDA  YCRD 
STA  V 

JSR  PLOTFOUR 

LDA  XYL 
SEC 

SBC  YCRD 


;  YCRD  <- CYMID-R23 
;  X  <-YMID  FOR  LATER 


;X£<  <-C£*XMID! 


;  A  <-YMID 

;Y£  <  <-C£*YMIDI 


; YCRDF <-0 


; A  <-YM ID 

; XY <  <— CXMID+YMID3 


;XCRD<  <-CXMID-R£3 


; H ( <-XCRD 


;  V  <  <-YCRD 


;  PLOT  SET  OF  POINTS 
;H  <  <— EXY-YCRDI 
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08D5 

8D 

£E 

09 

109 

ST  A 

HL 

08D8 

ftD 

38 

09 

110 

LDft 

XYH 

08DB 

E9 

00 

111 

SBC 

#0 

08DD 

8D 

£D 

09 

1 1£ 

STft 

HH 

08E0 

113 

• 

5 

08E0 

ftD 

39 

09 

114 

LDft 

XYL 

; V  <- HXY-XCRD3 

08E3 

38 

115 

SEC 

08E4 

ED 

35 

09 

116 

SBC 

XCRDL 

08E7 

8D 

31 

09 

117 

STft 

V 

08EA 

118 

5 

08Eft 

£0 

£C 

08 

119 

JSR 

PLOTFOUR 

; PLOT  REMAINING  POINTS 

08ED 

1£0 

■ 

08ED 

AD 

3C 

09 

1£1 

LDft 

YMID 

; DIVISOR  <-[ YMID- YCRD 3 

08F0 

38 

1££ 

SEC 

08F 1 

ED 

3D 

09 

1£3 

SBC 

YCRD 

08F4 

85 

1ft 

1£4 

STft 

DIVISOR 

08F6 

1£5 

• 

? 

08F6 

ftD 

37 

09 

1£6 

LDft 

XMIDL 

; DIVIDEND  <- CXMID-XCRD3  *£56 

08F9 

38 

1£7 

SEC 

08Fft 

ED 

35 

09 

1£8 

SBC 

XCRDL 

08FD 

1£9 

5 

08FD 

ft£ 

08 

130 

LDX 

#8 

; BITCT  <-8 

08FF 

131 

5 

08FF 

ft0 

00 

13£ 

LDY 

#0 

; CLEAR  QUOTIENT 

0901 

84 

IB 

133 

STY 

QUOTIENT 

0903 

134 

5 

0903 

06 

IB 

135 

DIVIDEl 

fiSL 

QUOTIENT 

0905 

£ft 

136 

ROL 

0906 

C5 

1A 

137 

CMP 

DIVISOR 

0908 

90 

04 

138 

BCC 

DIVIDES 

090ft 

E5 

1ft 

139 

SBC 

DIVISOR 

090C 

E6 

IB 

140 

INC 

QUOTIENT 

090E 

Cft 

141 

DIVIDES 

DEX 

090F 

D0 

F£ 

14£ 

BNE 

DIVIDEl 

091 1 

143 

5 

091 1 

ftD 

3E 

09 

144 

LDft 

YCRDF 

; YCRDF <- CYCRDF-QUOTIENT3 

0914 

38 

145 

SEC 

0915 

E5 

IB 

146 

SBC 

QUOTIENT 

0917 

8D 

3E 

09 

147 

STft 

YCRDF 

091ft 

148 

■ 

? 

091ft 

B0 

03 

149 

BCS 

CKX 

; YCRDY  <  -1? 

09 1C 

CE 

3D 

09 

150 

DEC 

YCRD 

; YES, YCRD  <- CYCRD-13 

09  IF 

151 

5 

091F 

EE 

35 

09 

1 5£ 

CKX 

INC 

XCRDL 

; XCRD  <  <  —  CXCRD+1 3 

09££ 

D0 

03 

153 

BNE 

CKX  1 

09£4 

EE 

34 

09 

154 

INC 

XCRDH 

09£7 

155 

5 

09£7 

CE 

30 

09 

156 

CKX  1 

DEC 

R£ 

; TALLY  R£ 

09£ft 

10 

8D 

157 

BPL 

NXPOINT 

; REPEAT  UNTIL  XCRD=XMID 

09£C 

60 

158 

RTS 

09£D 

159 

5 

09£E 

160 

HH 

DFS 

1 

; HORIZONTAL  PLOT  VftLUE 

09£F 

161 

HL 

DFS 

1 

_ _ n  i 

(Continued  on  page  28) 
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wIPC  ICS  (Listing  continued,  text  begins  on  page  18) 

Listing  Two 


0930 

162 

R 

DFS 

1 

; RAD I US 

0931 

163 

R2 

DFS 

1 

; HOLDS  R/SQR (2) 

0932 

164 

V 

DFS 

1 

; VERTICAL  PLOT 

0933 

165 

X2H 

DFS 

1 

; HOLDS  XMID*2 

0934 

166 

X2L 

DFS 

1 

0935 

167 

XCRDH 

DFS 

1 

; X  COORDINATE 

0936 

168 

XCRDL 

DFS 

1 

0937 

169 

XMIDH 

DFS 

1 

; HORIZONTAL  CENTER 

0938 

170 

XMIDL 

DFS 

1 

0939 

171 

XYH 

DFS 

1 

; HOLDS  XMID+YMID 

093A 

172 

XYL 

DFS 

1 

093B 

173 

Y2H 

DFS 

1 

; HOLDS  YMID*2 

093C 

174 

Y2L 

DFS 

1 

093D 

175 

YMID 

DFS 

1 

; VERT I CAL  CENTER 

093E 

176 

YCRD 

DFS 

1 

; Y  COORDINATE 

093F 

177 

YCRDF 

DFS 

1 

; FRACTIONAL  PART  OF  YCRD 

093F 

178 

■ 

9 

001A 

179 

DIVISOR 

EPZ 

$1A 

C052 

180 

FULL 

EQU 

$0052 

0050 

181 

GRAPHICS 

EQU 

$0050 

00E4 

182 

HCOLOR 

EPZ 

$E4 

0057 

183 

HIRES 

EQU 

$0057 

F457 

184 

HPLOT 

EQU 

$F457 

; APPLESOFT  HIRES  PLOT 

00E6 

185 

HPAGE 

EPZ 

$E6 

00E1 

186 

LASTHH 

EPZ 

$E1 

;HORIZ  COORD  OF  LAST  HPLOT 

00E0 

187 

LASTHL 

EPZ 

$E0 

00E2 

188 

LASTV 

EPZ 

$E2 

; VERT  COORD  OF  LAST  HPLOT 

0054 

189 

PAGE1 

EQU 

$0054 

001B 

190 

QUOTIENT 

EPZ 

$  IB 

093F 

191 

■ 

9 

093F 

192 

END 

*****  END  OF  ASSEMBLY 


End  Listing  Two 
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Listing  Three 


10  *  *  *  *  CIRCL £  PLOT  *** 

20 

30  INPUT  "CENTER,  RADIUS”;  CX , CY , R  :  X  =  R:  Y=0:  A  =  -2*X+1: 

8= 1 :  GOSUB  70 :  GOTO  30 
40 

5  0  ’  PLOT  A  POINT  IN  EACH  OCTANT „ 

60 

70  PSET(X  +  CX,  Y-fCY)  :  PSET  (  Y  +  CX  ,  X  +  CY  )  :  PSET  (  -  Y  +  CX  ,  X  +  CY  )  : 

PSET(-X4CX,Y  +  CY)  :  PSET ( -X+CX , -Y  +  CY  )  :  PSET(-Y  +  CX,-X4CY)  : 
PSET(Y4CX,-X4CY)  :  PSET(X4CX, -Y  +  CY  ) 

80 

9  0  'COMPUTE  NEXT  POINT.  E  IS  X~2+Y~2-R~2 ,  A  IS  THE  CHANGE 

100  1  IN  X~2  /THEN  X  IS  DECREMENTED  BY  I ,  AND  B  IS  THE  CHANGE 

110  'IN  Y~2  WHEN  Y  IS  INCREMENTED  BY  1 .  E  IS  NOT  ALLOWED  TO 

120  'EXCEED  R;  EQUIVALENTLY,  THE  POINT  (X.Y)  IS  KEPT  WITHIN 

130  'A  DISTANCE  R+  1/2  OE  THE  CIRCLE  CENTER.  THE  ALGORITHM 
140  'IS  DONE  WHEN  THE  CHANGE  IN  Y~2  REACHES  THE  NEGATIVE  OE 
150  ’  THE  CHANGE  IN  X~2  (  B>  =  -A  J. 

160 

170  IE  B>  =  -  A  THEN  RETURN  ELSE  Y=Y4l:  F  =  F  +  B:  IF  F  >R  THEN 
F--F4A:  A  =  A42:  X  =  X4l 
180  B=B42:  GOTO  70 

End  Listing  Three 


Circles 

Listing  Four 

10  DEFINE  A-Z 

20  PRINT  CHR$ (26)  'CLEAR  DUMB  TTY  SCREEN 

50  FOR  1=1  TO  11 

55  AE=I*2  'WIDTH  OF  ELLIPSE 

5b  BE=I*1  'HEIGHT  OF  ELLIPSE 

57  XC=I*4+1  ' CENTER. X  OF  ELLIPSE 

5b  YC=I*1  'CENTER. Y  OF  ELLIPSE 

6U  GOSUB  1060  'PLOT  A  CIRCLE 

7u  NfcXT  I  'PLOT  11  CIRCLES 

998  END 

1050  '******  CIRCLE  SUBROUTINE 

1060  XF=0  ' INIT  X-OFFSET 

10 /u  YF=BE  'INIT  Y-OFFSET 

108u  XD=BE*BE  'INIT  COMPUTATION  OF  X-SQUARED 

109u  YD= (2*BE-1 ) *AE*AE  'INIT  COMPUTATION  OF  Y-SQUARED 

1100  DX=2*BE*BE  'DEFINE  DELTA- (X-SQUARED) 

1110  DY=2*AE*AE  'DEFINE  DELTA- (Y-SQUARED) 

1120  ER=0  'INIT  ERROR  (I.E.  ER=AE~2*BE~2-XF?2*BE/'2-YF~2*AE''2) 

1130  GOSUB  1260  'PLOT  THE  FOUR  POINTS 

11 4U  TX=ER+XD 
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:  TY=ER-YD 
:  TB=ER+XD-YD 

1150  IF  ABS  (TX)  >=ABS  (TY)  OR  ABS  (TX)  >=ABS  (TB)  THEN  1170 
1160  XF=XF+1 

:  ER=TX 
:  XD=XD+DX 
:  GOTO  1220 

117 U  IF  ABS  (TY)  >=ABS(TX)  OR  ABS  (TY)  >=ABS(TB)  THEN  1190 
118u  YF=YF-1 

:  ER=TY 
:  YD=YD-DY 
:  GOTO  1220 

119u  IF  ABS  (TB)  >=ABS  (TX)  OR  ABS  (TB)  >=ABS  (TY)  THEN  1210 
1200  XF=Xf+1 

:  YF=YF-1 
:  ER=TB 
:  YD=YD-DY 
:  XD=XD+DX 
:  GOTO  1220 

1210  PRINT  "OOPS";  'IF  HERE  THEN  THERE  IS  A  BUG. 

1220  GOSUB  1260  'PLOT  THE  POINTS 
1230  IF  YFOO  THEN  1140 
1240  RETURN 

1250  '******  ROUTINE  TO  PLOT  FOUR  POINTS  AT  ONCE 
126U  XP=XC+XF 

:  YP=YC+YF 
:  GOSUB  1320 
127u  XP=XC+XF 

;  YP=YC-YF 
:  GOSUB  1320 
128u  XP=XC-XF 

:  YP=YC+YF 
:  GOSUB  1320 
129u  XP=XC-XF 

:  YP=YC-YF 
:  GOSUB  1320 
1300  RETURN 

1310  '******  ROUTINE  TO  PLOT  A  POINT  ON  A  DUMB  TERMINAL 
1320  Cl=YP+32 

:  C2=XP+32 

1330  IF  YP<0  OR  YP>23  OR  XP<0  OR  XP>79  THEN  1360 
134u  PRINT  CHR$(27)  ;CHR$(61)  ;CHR$(C1)  ;CHR$(C2) 

13d0  RETURN 

1360  PRINT  "POINT  OUT  OF  BOUNDS" 

:  STOP 


End  Listing  Four 
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Cursor  Control  for 
Dumb  Terminals 


A  friend  of  mine  asked  me  one  day, 
“Why  should  1  purchase  a  new  CRT 
terminal  when  I  can  buy  a  surplus 
unit  for  less  than  half  the  price?” 

“Because,”  I  answered, “that  so-called 
bargain  of  yours  is  what  we  used  to  call  a 
‘dumb’  terminal.  Unlike  today’s  marvels, 
it  has  only  the  most  basic  of  cursor  con¬ 
trol  functions:  home,  line  feed,  carriage 
return,  backspace,  and  skip  (the  skip  func¬ 
tion  moves  the  cursor  across  the  screen 
one  column  at  a  time  without  deleting 
any  currently  at  that  position).  It  is  inca¬ 
pable  of  direct  cursor  addressing,  which  is 
required  by  most  of  the  software  available 
on  the  market  today.  In  short,  it  is  not  a 
bargain;  it  is  an  antique.” 

•  “What,”  my  friend  asked,  “should  I 
do  with  this  antique  I  just  bought?” 

The  solution  to  his  problem  turned 
out  to  be  surprisingly  simple  and  should 
be  of  interest  to  anyone  owning  a  terminal 
without  direct  cursor  addressing  and  a 
microcomputer  system  running  CP/M.  (It 
should  also  interest  those  wanting  to  con¬ 
nect  more  esoteric  peripherals  than  ter¬ 
minals  or  printers  to  their  systems,  if  only 
to  illustrate  the  level  of  complexity  that 
can  be  supported.)  Only  the  software 
need  be  modified.  Even  then  the  CP/M 
operating  system  remains  absolutely  stan¬ 
dard  and  is  still  capable  (assuming  the 
IOBYTE  feature  has  been  implemented) 
of  supporting  a  second  terminal  with 
direct  cursor  addressing  without  further 
modifications.  What  more  could  you 
ask  for? 

A  terminal  with  direct  cursor  addres¬ 
sing  traps  a  predefined  string  of  ASCII 
characters  sent  from  the  computer  to  the 
terminal  and  uses  the  information  con¬ 
tained  in  this  string  to  position  the  cursor 
on  the  screen.  (The  string  itself,  of  course, 
is  not  displayed.)  As  an  example,  the  Tele¬ 
video  950  terminal  responds  to  the  ASCII 
string  “ESC=yx,”  where  y  is  an  ASCII 
character  from  “SP”  (32  decimal)  to 
“7”  (55  decimal)  that  positions  the  cur¬ 
sor  vertically  and  x  is  an  ASCII  character 
from  “SP”  to  “o”  (111  decimal)  that 
positions  the  cursor  horizontally.  To  em¬ 
ulate  this  feature,  a  “dumb”  terminal 
should  be  able  to  respond  to  a  similar 
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string  of  ASCII  characters  and  position  its 
cursor  accordingly. 

While  it  would  be  nice  to  have  the 
terminal  perform  this  function  through 
its  own  hardware,  this  is  obviously  im¬ 
practical  for  a  large  number  of  users;  re¬ 
designing  and  rewiring  old  printed  circuit 
boards  without  schematics  is  a  task  few 
care  to  tackle!  What  remains  is  to  modify 
the  software,  specifically  CP/ M’s  BIOS 
(Basic  Input/ Output  System),  which  pro¬ 
vides  the  interface  between  the  terminal 
and  the  host  computer.  The  CP/M  oper¬ 
ating  system  can  then  monitor  what  the 
running  program  is  sending  through  the 
BIOS  to  the  terminal. 

When  an  ASCII  “ESC”  character  is 
sent  to  the  modified  BIOS  (from,  say,  a 
full-screen  word  processing  program),  it 
will  store  this  character  temporarily  rather 
than  output  it  through  the  serial  port  to 
the  terminal.  When  the  next  character 
sent  by  the  program  is  received,  the  BIOS 
will  check  to  see  if  it  is  an  ASCII  “=” 
character.  If  it  isn’t,  the  BIOS  will  output 
both  the  stored  “ESC”  character  and  the 
received  character  to  the  terminal,  then 
continue  to  output  characters  received 
from  the  program  until  the  next  “ESC” 
character  arrives;  otherwise,  it  will  recog¬ 
nize  the  two  characters  as  the  start  of  a  di¬ 
rect  cursor  positioning  command,  discard 
them,  and  wait  for  the  next  character. 

Once  this  character  is  received,  the 
BIOS  will  decode  it,  output  a  single 
ASCII  control  character  to  home  the 
cursor  on  the  terminal,  and  output  the 
required  number  of  line  feeds  to  position 
the  cursor  vertically.  Then  it  will  trap  the 
next  character  sent  by  the  program, 
decode  it,  and  output  the  required  num¬ 
ber  of  skip  control  characters  to  position 
the  cursor  horizontally.  Once  the  cursor 
is  positioned  where  required,  everything 
returns  to  normal;  all  ASCII  characters 
sent  to  the  BIOS  by  the  program  will  be 
sent  to  the  terminal  after  being  monitored 
for  an  “ESC”  character  and  the  possible 
start  of  another  direct  cursor  positioning 
command. 

It  sounds  complicated,  but  it  is  sim¬ 
ple  to  program  and  works  beautifully  as 
long  as  you  operate  the  terminal  at  9600 
baud.  At  this  speed  the  cursor  will  take, 
in  the  worst  case,  approximately  one- 
tenth  of  a  second  to  traverse  the  screen 
(from  the  home  position  to  the  24th  row 
and  80th  column).  The  motion  of  the 
cursor  is  perceptible  but  not  objectiona¬ 
ble;  a  slower  baud  rate,  however,  is  an 
invitation  to  crossed  eyeballs  from  watch¬ 


ing  the  cursor  bounce  around  the  screen ! 

The  entire  software  routine  can  be 
written  as  a  peripheral  driver  and  added 
to  your  BIOS  in  exactly  the  same  way  as 
you  would  add  a  printer  or  modem  to 
your  system. 

If  your  version  of  CP/M  doesn’t  in¬ 
clude  the  IOBYTE  feature,  then  the 
accompanying  code  (Listing  One,  page 
33)  should  be  substituted  for  your  exist¬ 
ing  terminal  driver  (usually  the  physical 
device  TTY:  or  CRT:  in  the  BIOS  source 
code).  Once  this  is  done,  your  version  of 
CP/M  will  be  customized  for  the  “dumb” 
terminal  being  used  as  its  console  device. 
When  a  newer  model  terminal  is  pur¬ 
chased,  the  BIOS  must  be  customized 
once  again  to  support  it  as  the  console 
device  instead  of  the  old  terminal. 

Fortunately,  most  commercial  ver¬ 
sions  of  CP/M  do  include  the  IOBYTE 
feature.  In  this  case,  the  accompanying 
code  should  be  placed  in  whatever  physi¬ 
cal  I/O  device  driver  routine  isn’t  being 
used  (usually  the  user-defined  console 
device  UC1:).  By  leaving  the  TTY:  or 
CRT:  physical  device  code  (whichever 
currently  supports  the  computer’s  ter¬ 
minal  device)  intact  or  by  modifying  it 
to  support  the  terminal  you  eventually 
intend  to  purchase,  you  can  switch  be¬ 
tween  a  “dumb”  terminal  and  a  modern 
direct-cursor-addressable  terminal  simply 
by  using  the  STAT  CON:=UCl:  and 
STAT  CON:=TTY:  (or  STAT  CON:=CRT:, 
as  applicable)  commands.  You  can  also 
modify  your  BIOS  to  initially  set  the  IO¬ 
BYTE  so  that  CON:=UCl:  after  each 
cold  boot. 

Because  the  procedure  for  modifying 
CP/M’s  BIOS  may  vary,  depending  on  the 
idiosyncracies  of  your  particular  system,  I 
will  not  describe  it  in  this  article.  If  you 
haven’t  interfaced  a  peripheral  to  your 
system  before,  I  suggest  that  you  have 
your  vendor  or  an  experienced  friend  per¬ 
form  the  modifications  indicated  in  List¬ 
ing  One;  otherwise,  you  should  consult 
some  of  the  excellent  books  on  CP/M 
that  are  available  (the  finest  I  know  of  is 
David  Cortesi’s  Inside  CP/M  -  A  Guide 
for  Users  and  Programmers,  CBS  College 
Publishing,  1982). 

By  the  way,  some  excellent  bargains 
are  available  on  the  surplus  computer 
equipment  market  —  if  you  know  exact¬ 
ly  what  you  are  buying.  Otherwise,  caveat 
emptor,  or  “let  the  buyer  beware !  ”  bbj 
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Cursor*  Control  Listing  (Text  begins  on  page  32) 


?  *************************************************************** 


* 

* 

* 

CP/M  BIOS  Modi f i ca t i ons 

* 

* 

# 

* 

Author: 

Ian  Ashdown 

* 

* 

byHeart  Software 

* 

* 

2  -  2016  West  First  Avenue 

* 

* 

Vancouver ,  B.C.  V6J  1GS 

* 

* 

* 

* 

Date: 

February  10th/  1983 

* 

* 

* 

;  ********  *******  *****************-fc  *****************-)HHHMt******** 

5 

5  The  following  code  has  been  added  to  allow  the  ANAND  II  "dumb" 

>  terminal  to  emulate  a  direc t -aridressab 1 e  cursor  terminal 
5  ( spec i f ica l i y  the  TELEVIDEO  950).  It  does  this  by  trapping  an 

;  "ESC^yx"  control  code  from  a  program  and  interpreting  "y"  as 
;  the  vertical  row  address  (where  20H  is  row  #1)  and  "x"  as  the 
$  horizontal  column  address  of  the  cursor  (where  20H  is  column 
;  «1).  The  BIOS  then  homes  the  cursor  and  outputs  as  many  line 
;  feeds  and  sKips  as  is  required  to  position  the  cursor  witnout 
;  changing  the  current  screen  display.  At  9600  baud  the  worst 
;  case  transit  time  of  the  cursor  (from  "home"  to  the  24th  row 
;  and  80th  column)  is  approximate  I y  i/10  second. 

? 

;  **************************  EQUATES  **************************** 


;  NOTE: 


LF 

CR 

ESC 


The  following  equates  are  independent  of  the  system  used. 
However t  they  may  already  be  defined  in  your  BIOS  source 
code. 


EQU  OAH  $  ASCI  I  line  feed 

EQU  ODH  ;ASCII  carriage  return 

EQU  1BH  ; ASCI  I  escape 


;  NOTE:  The  following  equates  are  specific  to  my  California 
;  Computer  System's  serial  I/O  port  and  the  control  cooes 

;  recoqnized  by  the  ANAND  II  terminal.  Replace  them 

;  with  those  required  by  your  system. 


RESET 

EQU 

19H 

; ANAND  II  "home  cursor"  control  char. 

SKIP 

EQU 

14H 

; ANAND  II  "cursor  forward"  control  char 

SDATA 

EQU 

20H 

; SERIAL  DATA  PORT 

SLSTAT 

EQU 

SDATA+5 

; Serial  line  status  port 

FtXRDY 

EQU 

00000001B  ^Receive  data  available  bit 

TXMTY 

EQU 

00100000B  ; Transmit  buffer  empty  bit 

^  **•#****■*■#•*  NEW  PHYSICAL  DEVICE  LJC1:  DRIVER  ROUTINE  ***■**•**■#•■**■*•#• 


;  I/O  DRIVERS  FOR  THE  8250  ASYNC  COMM  ELEMENT 
;  (PHYSICAL  DEVICE  UC1:> 
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;  NOTE: 

The  fol 

low inq 

CUST1:  and  CUSH:  suflrou  tines  are  vendor - 

> 

dependent  code 

(see  COMMENTARY  at  the  end  of  this 

> 

1 ist ing) ,  and 

should  be  replaced  with  the  TTY:  or  CRT: 

• 

y 

driver 

code  sp 

ecific  to  your  system. 

OUST 1 : 

IN 

SLSTAT 

?Get  8250  line  status 

ANI 

RXRDV 

;See  if  receive  data  available 

R2 

; Re turn  if  not 

ADI 

OFFH  AND  NOT  RXRDY  ;F'lag  that  data  is 

RET 

; avai 1 ab 1 e 

CUSH: 

CALL 

CUST1 

5 Get  8250  line  status 

JZ 

CUSI1 

;Loop  until  data  is  in 

IN 

SDATA 

;Read  the  data 

RET 

;  NOTE: 

The  fo)  1  aw inq 

subroutines  CUS01:  throuqh  HORZOUT: 

5 

inclusive  are 

independent  of  the  system  used. 

CUS01: 

LDA 

ESCF'TR 

;Get  escape  sequence  pointer 

CPI 

0 

;Jump  to  TESTCH  if  this  isn't  an 

JZ 

TESTCH 

; escape  sequence 

CF'l 

1 

:Jump  to  TESTEQU  if  this  is  an  escape 

JZ 

TESTEQU  ^ sequence 

CPI 

2 

; Jump  to  VERTIN  if  true  (character  is 

JZ 

VERTIN 

5 row  address  of  cursor) 

JMP 

HORZIN 

;  Jump  to  HORZIN  (character  is  column 

5 address  of  cursor ) 

TESTCH: 

NOV 

A,C 

;Get  character  from  register  C 

CPI 

ESC 

? Jump  to  NOTESC  if  it  isn't  an  ASCII  ESC 

JNZ 

NOTESC 

MV  I 

A,1 

;Set  escape  sequence  pointer  to  i  to 

STA 

ESCF'TR 

; indicate  ASCII  ESC  cnaracter 

RET 

NOTESC : 

CALL 

CUSOUT 

5  Out  put  character 

RET 

TESTEQU 

:  MOV 

A  f  C 

5 Get  character  from  register  C 

CPI 

;  Jump  to  NOTEQU  if  it  isn't  an  ASCII  '= 

JNZ 

NOTEQU 

MV  I 

A, 2 

;Set  escape  sequence  pointer  to  2  to 

STA 

ESCF'TR 

; indicate  ASCII  ”="  character 

RET 

NOTEQU: 

MVI 

A  ,0 

;Set  escape  sequence  pointer  to  0  (false 

STA 

ESCPTR 

$  a  1  arm ) 

MVI 

A,  ESC 

? Out  put  previous  ASCII  ESC  character 

CALL 

CUSOUT 

MOV 

A,C 

$Get  current  character  from  register  C 

CALL 

CUSOUT 

; Ou  t  pu  t  it 

RET 

5 


(Continued  on  page  36) 
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Cursor  Control  Listing  (Listing  continued,  text  begins  on  page  32) 


VERT IN: 

MOV 

A,C 

$Get  character  from  register  C 

SUI 

1FH 

; Sub tract  cursor  address  bias  (20H  is  row 
5 number  i)  to  get  row  address  counter 

MOV 

C,A 

5 Store  row  address  counter  in  register  C 

MV  I 

A, 3 

$Set  escape  sequence  pointer  to  3 

STA 

ESCPTR 

MV  I 

A /RESET 

^Output  “reset  cursor"  control  character 

CALL 

CUSOUT 

VERTGUT 

:  DCR 

C 

; Decrement  row  address 

RZ 

$ Re  t urn  i f  done 

MV  I 

A,LF 

^Output  a  line  feed 

CALL 

CUSOUT 

JMP 

VERTOUT 

5  Loop  until  done 

HORZIN: 

MOV 

A,C 

$Get  character  from  register  C 

SUI 

1FH 

\ Subtract  cursor  address  bias  (20H  is 

MOV 

C,A 

; column  number  1)  to  get  column  counter 

XRA 

A 

•Set  escape  sequence  pointer  to  0 

STA 

ESCPTR 

HORZOUT 

:  DCR 

C 

5 Decrement  column  counter 

RZ 

^ Re turn  if  done 

MV  I 

A, SKIP 

; Out  put  a  "cursor  skip”  control  character 

CALL 

CUSOUT 

JMP 

HORZOUT 

;Loop  until  done 

ESCPTR 

DB 

0 

$  Escape  sequence  pointer 

\  NOTE: 

The 

following  CUSTQUT :  subroutine  is  vendor-dependent 

? 

code 

(see  COMMENTARY  at  the  end  of  this  listing) >  and 

5 

shou 

Id  be  replaced  with  the  TTY:  or  CRT:  driver  code 

5 

specific  to  your 

system. 

CUSOUT: 

PUSH 

F'HW 

;Save  cnaracter 

CUSOUT1 

:  CALL 

CUSOST 

;Get  8250  line  status 

JZ 

CUS0UT1 

?Wait  until  one  of  the  registers  empties 

POP 

F‘SW 

^Recall  character 

OUT 

SDATA 

5  Out  put  the  data 

RET 

CUSOST: 

IN 

SLSTAT 

;Get  3250  line  status 

ANI 

TXMTY 

; Isolate  TX  buffer  empty  bit 

RZ 

; Re turn  if  not  empty 

ADI 

OFFH  AND 

NOT  TXMTY  ;Flag  the  empty  state 

RET 

y 

;  ***********************  DELETED  CODE  ************************** 
5 
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;  The  following  code  has  been  deleted: 

•CUSH:  EQU  IOER  *  UNASSIGNED  USER  CONSOLE  (INPUT) 

; CUS01 :  EQU  IOER  ; UNASSIGNED  USER  CONSOLE  (OUTPUT) 

5  CUST 1 :  EQU  IOER 

5 

5  ************************  COMMENTARY  *************************** 
5 

;  The  following  California  Computer  Systems  vendor  code  for  a 
;  typical  serial  interface  to  a  terminal  has  oeen  added  for 
;  information  only  as  an  example  to  show  where  the  I/O  portion 
^  of  the  above  UCl:  code  was  derived  from*  Most  CF'/M  TTY:  and 
5  CRT:  physical  device  drivers  will  be  similar  to  this  code. 

*  I/O  DRIVERS  FOR  THE  8250  ASYNC  COMM  ELEMENT 
?  (PHYSICAL  DEVICE  TTY:) 


; TTST : 

IN 

SLSTAT 

; GET  8250  LINE  STATUS 

AN  I 

RXRDY 

; SEE  IF  RECEIVE  DATA  AVAILABLE 

RZ 

; RETURN  IF  NOT 

5 

ADI 

OFFH  AND 

NOT  RXRDY  ; FLAG  THAT  DATA  IS 

? 

RET 

; AVAILABLE 

;TTYIN: 

CALL 

TTST 

; GET  8250  LINE  STATUS 

5 

JZ 

TTY  IN 

; LOOP  UNTIL  DATA  IS  IN 

IN 

SDATA 

;  REACi  THE  DATA 

5 

RET 

; TTQST : 

IN 

SLSTAT 

? GET  8250  LINE  STATUS 

% 

* 

AN  I 

TXMTY 

? ISOLATE  TX  BUFFER  EMPTY  BIT 

5 

RZ 

; RETURN  IF  NOT  EMPTY 

5 

ADI 

OFFH  AND 

NOT  TXMTY  $  FLAG  THE  EMPTY  STATE 

5 

RET 

* 

; TTYOUT 

:  CALL 

TTOST 

; GET  8250  LINE  STATUS 

5 

JZ 

TTYOUT 

5  WAIT  UNTIL  ONE  OF  THE  REGISTERS  EMPTIES 

5 

MOV 

A,C 

; MOVE  THE  DATA  OVER 

% 

> 

OUT 

SDATA 

; OUTPUT  THE  DATA 

« 

* 

RET 

5 

*  ***********************  END  OF  LISTING  ************************ 


End  Listing 
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Dysan  5s  Digital  Diagnostic 
Diskette 


Dilemma:  You’ve  been  seeing  more 
flexible  disk  errors  lately,  especially 
when  swapping  disks  between  your 
drives.  But  they  seem  to  work  properly 
most  of  the  time,  so  you  struggle  on,  tol¬ 
erating  the  occasional  loss  of  your  data, 
frustration,  and  wasted  time.  After  all, 
you’re  not  sure  anything  is  wrong  with 
the  drives;  to  find  out,  you’d  have  to 
remove  one  from  the  system  and  ship  it 
off  to  a  stranger  who  probably  makes 
money  five  times  as  fast  as  you  do.  If  the 
problem  persisted  after  the  drive  came 
back,  would  you  send  another  one  off  to 
be  checked? 

Deliverance:  Now,  for  less  than  what 
you’d  probably  spend  having  one  drive 
professionally  checked,  you  can  equip 
yourself  to  verify  the  operation  of  all 
your  flexible  disk  drives,  anytime  you 
suspect  a  problem,  without  disassembling 
or  altering  your  system!  But  you’ll  have 
to  begin  now,  before  you  have  serious 
operating  problems  —  partly  because 
you’ll  have  to  customize  a  public  domain 
program  to  fit  the  quirks  of  your  terminal 
and  disk  controller,  but  mainly  because 
you’ll  want  to  have  a  “before”  picture  of 
your  drives’  operation  to  help  you  recog¬ 
nize  any  real  problems  that  may  appear 
later. 

You  thought  a  drive  exerciser  and 
dual- channel  triggered  sweep  oscilloscope 
were  essential  for  flexible  drive  alignment? 
Well,  the  Dysan  Corporation,  which  makes 
the  Analog  Alignment  Diskette™  for 
scope  alignment,  now  offers  a  Digital 
Diagnostic  Diskette™.  Using  your  own 
computer  system  and  the  program  de¬ 
scribed  in  this  article,  you’ can  verify  your 
drives’  alignment  to  within  one-half 
milli-inch  of  the  expensive  analog  method. 
Plus,  you  can  check  the  spindle  bearings 
and  clamping  mechanism,  verify  spindle 
speed,  check  positioner  hysteresis  (worn 
lead  screw,  bad  stepper  motor,  etc.), 
verify  read /write  head  azimuth,  and 
check  index-hold  timing,  all  under  your 
own  operating  conditions. 


by  Loren  Amelang 


Loren  Amelang,  Box  24,  Philo,  CA 
95466-0024. 

“Analog  Alignment  Diskette,”  “AAD,” 
“Digital  Diagnostic  Diskette,” and  “DDD” 
are  trademarks,  and  “Dysan  ”  is  a  regis¬ 
tered  trademark,  of  Dysan  Corporation. 


What  the  DDD  Is 

The  Digital  Diagnostic  Diskette 
(DDD™)  looks  like  any  other  floppy 
disk.  It  has  ordinary  formatting,  and  con¬ 
ventional  data  are  recorded  on  it.  Figure  1 
(page  42)  shows  a  small  sample  of  disk  data 
patterns  to  scale.  You  could  probably  run 
your  disk  copy  program  and  duplicate  it. 
But  your  copy  would  not  be  another  DDD! 
The  digital  alignment  concept  depends 
upon  having  the  data  fields  of  the  DDD 
carefully  displaced  from  their  proper  loca¬ 
tion  or  azimuth  by  known  amounts. 

For  example,  let’s  look  at  the  center¬ 
ing  test.  Three  “alternate  offset”  tracks 
on  the  DDD  are  offset  7,  8,  and  9  milli- 
inches  from  the  official  center  of  the 
track  (see  Figure  2,  page  42).  (All  values 
given  are  for  48  track-per-inch  drives;  if 
you  have  96  or  100  tpi  drives,  tolerances 
are  tighter  and  thus  offsets  are  smaller.) 
All  odd-numbered  sectors  are  displaced 
toward  the  center  of  the  disk,  and  even- 
numbered  sectors  toward  the  outside 
edge.  Your  head  gap  is  designed  to  pick 
up  a  12  milli-inch  swath  of  data,  so  if  it  is 
perfectly  aligned  but  the  data  are  offset 
7  milli-inches,  it  “sees”  only  5  milli-inches 
of  the  data.  In  analog  terms,  the  ampli¬ 
tude  of  the  signal  is  reduced  drastically; 
in  digital  terms,  either  your  drive’s  elec¬ 
tronics  can  make  sense  of  the  weak  signal, 
or  you  get  a  read  error.  As  you  move  to 
the  9  milli-inch  offset  track,  the  width 
of  the  recorded  data  still  under  a  properly 
positioned  head  is  reduced  to  3  milli- 
inches;  if  your  spindle  bearings  have  .003 
inches  of  play,  the  signal  may  disappear 
entirely  at  certain  points.  If  your  head  is 
dirty,  and  the  accumulated  oxide  holds  it 
away  from  proper  contact  with  the  media, 
the  already  reduced  signal  amplitude  will 
be  cut  still  further.  On  the  other  hand,  if 
your  system  can  reliably  read  data  that 
are  offset  9  milli-inches  in  either  direction, 
you  can  be  pretty  sure  that  your  drive  is 
mechanically  sound,  its  head  is  reasonably 
aligned,  and  its  electronics  are  not  being 
swamped  by  stray  electrical  or  magnetic 
fields. 

If  you  want  to  pin  down  more  exact¬ 
ly  the  radial  alignment  of  your  read/write 
head,  the  DDD  has  “progressive  offset” 
tracks  (Figure  3,  page  44).  Here  sector 
one  is  offset  1  milli-inch  toward  the  spin¬ 
dle,  sector  two  1  milli-inch  away,  sector 
three  2  milli-inches  toward  the  spindle, 
and  so  on  out  to  13  milli-inches  in  either 
direction.  (This  applies  to  Revision  B; 
Revision  A  DDD  had  ±  10  milli-inch  maxi¬ 
mum  offsets.)  You  read  through  the  odd- 


numbered  and  then  the  even-numbered 
sectors,  noting  the  first  sectors  that 
cannot  be  read.  This  information  can  be 
translated  into  a  graphic  display  of  your 
effective  head  width  and  its  position  rela¬ 
tive  to  proper  alignment.  Electrical  or 
magnetic  noise  in  your  environment, 
“dirt”  on  your  head,  or  improper  head 
loading  will  narrow  the  effective  head 
width.  A  major  advantage  of  the  DDD  is 
that  you  can  run  this  test  on  six  different 
tracks  spaced  across  the  diskette;  analog 
alignment  uses  only  one  central  track, 
with  the  hope  the  rest  will  follow. 

The  “azimuth  rotation”  track  is 
another  progressive  track  used  to  check 
whether  your  read/write  head  gap  is 
adversely  skewed  relative  to  the  data 
track.  Here  data  are  recorded  on  the  radial 
centerline  of  the  track,  but  the  head 
azimuth  is  progressively  rotated  away 
from  normal  (Figure  4,  page  46).  If  read 
errors  occur  symmetrically,  your  effective 
head  azimuth  is  correct.  If  your  system 
fails  in  one  direction  before  the  other, 
you  may  improve  performance  by  alter¬ 
ing  your  head  azimuth  toward  the  earlier 
angle.  Again,  a  decrease  in  azimuth  range 
could  indicate  a  dirty  head  or  environ¬ 
mental  noise. 

Other  recorded  DDD  tracks  contain  a 
special  formatting  pattern  for  timing  the 
passage  of  the  index  hole  past  your  sen¬ 
sor  and  for  detecting  how  long  it  takes 
your  head  to  settle  into  position  after  it 
is  loaded.  Finally,  some  tracks  are  marked 
“user  area,”  where  you  can  store  the  pro¬ 
gram  you’ll  need  to  read  the  DDD  and 
display  the  results.  Don’t  try  to  do  this 
under  CP/M  !  You’ll  overwrite  other  parts 
of  the  DDD  and  destroy  it!  If  you  are 
going  to  make  use  of  the  “user  area,” 
you’ll  need  a  “disk  doctor”  program  that 
can  write  to  specific  tracks  of  the  disk, 
and  you’ll  need  some  way  to  load  and  run 
what  you’ve  stored  without  involving 
CP/M. 

How  does  Dysan  Corporation  manage 
to  create  a  disk  with  precisely  misaligned 
information  on  it?  To  begin,  they  take 
their  premium  diskettes  and  screen  them: 
any  alignment  diskette  must  meet  high 
standards  for  dimensional  stability  and 
uniformity  of  the  recording  surface.  The 
DDD  must  be  error-free,  not  only  in  the 
normal  tracks  but  “in  the  cracks”  as  well. 
Critical  information  is  going  to  be  recorded 
completely  off  track  for  some  of  the  tests. 

Several  million  dollars  went  into  the 
computer-controlled,  laser-interferometer- 
calibrated  Hackwriters  and  the  environ- 
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mentally  standardized  room  that  houses 
them.  Once  the  blank  diskettes  have  ac¬ 
climated  to  the  standard  environment, 
they  are  individually  written;  the  track- 
writers  actually  move  the  write  heads  to 
all  those  different  off-track  positions. 
These  same  machines  write  the  Analog 
Alignment  Diskettes  used  by  manufac¬ 
turers  and  calibration  services.  The  same 
precise  standards  are  met,  both  for  the 
media  and  for  the  recorded  information. 
The  only  advantage  of' analog  alignment 
is  that  it  is  not  limited  to  resolving  the  1 
milli-inch  steps  of  the  DDD  but  can  get 
closer  to  the  exact  center  of  track.  Of 
course,  the  DDD  has  the  advantage  of 
being  able  to  check  alignment  on  six 
different  tracks  and  may  reveal  more 
than  one-half  milli-inch  of  variation 
between  the  inner  and  outer  track  centers. 

Using  the  DDD 

Dysan  Corporation  has  been  making 
the  DDD  for  about  two  years.  It  was  con¬ 
ceived  as  a  way  for  manufacturers  to  verify 
the  operation  of  completed  systems 
quickly,  without  having  to  reach  any  in¬ 
terior  test  points.  Field  service  personnel 
have  been  using  it  to  diagnose  drive  prob¬ 
lems  at  the  customer’s  location.  Recently, 
the  company  has  been  promoting  the 
DDD  to  end  users  at  various  computer 
shows. 

To  assist  the  end  user  in  creating  a 
program  that  reads  the  DDD  and  displays 
the  results  of  the  various  tests,  the  Custo¬ 
mer  Engineering  Division  of  Dysan  Cor¬ 
poration  developed  the  original  (version 
1.0)  DDD  program.  Designed  to  run  on 
their  “Single  Card  Computer”  with  a 
Hazeltine  1500  terminal,  version  1.0 
employs  direct-memory-access  (dma) 
transfers  of  read  data  and  requires  an 
8080  macro  assembler  for  assembly. 
Luckily  for  those  of  us  with  other  types 
of  equipment,  constants  are  clearly  de¬ 
fined  at  the  beginning  of  the  code,  and 
the  hardware-dependent  routines  are 
collected  at  the  end  of  the  code.  I  found 
the  macro  facility  was  rarely  used,  so  I 
expanded  the  few  examples  into  code 
that  ASM  can  handle.  Since  my  terminal 
does  not  have  a  clear-to-end-of-line  func¬ 
tion,  I  inserted  a  conditional  that  either 
prints  a  string  of  blanks  when  it  is  abso¬ 
lutely  essential  or  allows  those  who  have 
the  function  to  benefit  from  its  greater 
speed. 

This  still  leaves  a  few  basic  require¬ 
ments:  The  program  depends  heavily  on 
being  able  to  clear  your  terminal  screen 
and  address  your  cursor.  If  you  have  a 
really  dumb  terminal,  you  will  have  to 
completely  rethink  the  graphic  display 
parts  of  the  code.  The  program,  as  writ¬ 
ten,  commands  a  Western  Digital  1793 
floppy  disk  controller  chip;  if  your  sys¬ 
tem  does  not  use  this  chip,  you  will  have 
to  understand  both  the  1793  and  your 
own  controller  well  enough  to  translate 


commands  between  them.  Certain  con¬ 
troller  chips  are  not  capable  of  perform¬ 
ing  all  the  commands  the  program  uses, 
so  some  ingenuity  may  be  required.  Dif¬ 
ferent  systems  have  different  ways  of 
selecting  which  drive  is  to  be  tested.  I 
have  added  to  version  1.0  a  routine  to 
select  any  of  four  drives  connected  to  my 
CCS  2422  controller.  You’ll  have  to 
understand  how  your  system  goes  about 
selecting  drives.  Finally,  as  should  be 
obvious,  you’ll  need  to  be  able  to  deal 
with  8080  assembly  language  in  order  to 
get  the  DDD  program  working. 

Nothing  inherent  in  the  DDD  Emits 
it  to  CP/M  or  8080  systems.  It  is  available 
in  models  for  8-inch  or  5*/4-inch  drives; 
single  or  double  sided;  single  or  double 
density;  48,  96,  or  100  spi.  Since  the  DDD 
program  has  been  placed  in  the  public 
domain,  it  may  be  used  as  an  example  to 
construct  versions  for  other  machines, 
processors,  and  operating  systems.  If  you 
develop  a  version  for  a  popular  computer, 
I  hope  you’ll  make  it  available  on  a  bulle¬ 
tin  board  or  software  exchange. 

If  you’d  like  to  take  the  mystery 
out  of  your  flexible  disk  system,  and 
you’re  willing  to  be  guided  through  some 
hardware-intensive  assembly  language, 
here’s  your  agenda.  First,  order  a  DDD. 
If  you  have  double-sided  drives,  you’ll 
need  the  double-sided  DDD  in  order  to 
test  both  heads.  If  all  your  drives  have 
double-density  capability,  you’ll  want  to 
test  them  in  this  more  stringent  mode.  If 
some  are  single  density  only  and  your 
doubles  can  read  single,  perhaps  you’d 
prefer  a  single  DDD  for  all  of  them. 
You’ll  need  to  specify  the  disk  size  and 
number  of  tracks  per  inch.  Call  your 
local  Dysan  representative,  or  call  the 
factory  at  (408)  988-3472  or  (800) 
551-9000  outside  Northern  California, 
and  be  prepared  to  spend  $30.00  for  a 
single-sided  DDD  or  $40.00  for  a  double¬ 
sided  DDD,  plus  shipping  and  applicable 
taxes.  For  more  information  on  DDD 
applications,  call  Dysan’s  Tech-Line  at 
(408)  734-1624. 

Next,  you’ll  need  machine-readable 
source  code  for  the  program  that  reads 
the  DDD  and  displays  the  results. 
DDDU.ASM  (or  DDD11.AQM  in  the 
“squeezed”  version)  may  be  available  on 
your  local  RCPM  system.  If  you  have  a 
phone  line,  modem,  XMODEM-Protocol 
transfer  utility,  and  “Unsqueeze”  if 
DDD11.AQM  is  used  there,  you  can  copy 
the  program  yourself  for  free.  If  you 
must  call  long  distance,  be  warned  that 
DDDll.ASM  is  a  47K  file.  You  might  be 
better  off  downloading  it  from  Micronet’s 
CP/M  Interest  Group  “Access  area  1.”  If 
you  prefer  to  purchase  the  code  on  disk, 
contact  your  favorite  source  for  CP/MUG 
disks  or  write  CP/MUG,  1651  Third 
Avenue,  New  York,  NY  10028.  Should  all 

CA  95466-0024,  and  enclose  $10.00. 


Listing  One  (page  48)  contains  a  slightly 
abbreviated  version  of  DDDll.ASM, 
called  DDDCompact.ASM. 

Finally,  you’ll  need  some  informa¬ 
tion  about  your  hardware.  Check  your 
terminal’s  manual  to  see  if  it  gives  dear- 
screen  and  addressable  cursor-control 
commands.  See  if  your  disk  controller 
manual  gives  control  port  addresses,  com¬ 
mand  formats,  status  codes,  and  flow 
charts  of  command  execution.  If  the 
information  isn’t  there,  ask  the  manu¬ 
facturer  if  more  detailed  programming 
information  is  available.  While  a  source 
listing  of  your  CP/M  BIOS  would  probably 
reveal  what  you’ll  need  to  know  about 
the  disk  controller,  this  will  be  more  dif¬ 
ficult  to  decipher.  If  your  hardware  is 
based  on  an  LSI  controller  chip,  the  chip 
manufacturer’s  data  sheets  will  be  very 
helpful.  Save  yourself  frustration  by  col¬ 
lecting  your  hardware  information  before 
you  begin  —  while  you  wait  for  the  DDD 
disk  and  DDDll.ASM  to  arrive. 

Customizing  DDDll.ASM 
for  Your  System 

Once  you’ve  chosen  which  DDD  for¬ 
mat  you  need,  collected  your  hardware 
manuals,  and  are  seated  at  your  keyboard 
with  DDDll.ASM  in  your  editor,  we  can 
begin.  You’ve  read  the  headers  down  to 
“Program  Source  Code.”  The  first  instruc¬ 
tion  to  the  assembler  is  “wboot  equ  0” 
-  this  is  nearly  always  true.  If  you  hap¬ 
pen  to  be  dealing  with  a  nonstandard 
CP/M  system,  you  probably  are  well 
aware  of  the  fact;  you’ve  needed  special 
versions  of  programs  from  day  one  with 
your  system  and  will  have  to  modify  my 
recommendations  as  we  proceed. 

Next  come  the  “Conditionals.”  Here 
you  must  decide  how  committed  you  are 
to  good  programming  style.  The  quick 
way  to  customize  a  program  is  to  step 
through  the  code  and  change  only  a  few 
magic  numbers  until  it  works.  The  right 
way,  which  will  pay  off  handsomely  if 
you  should  want  to  give  the  program  to  a 
friend  or  need  to  understand  what  you 
did  come  next  year,  is  to  create  condi¬ 
tional  assembly  options  here  for  both 
your  terminal  and  your  disk  controller. 
Whenever  you  need  to  alter  a  bit  of  code 
in  the  body  of  the  program,  insert  “if 

My - ,”  enter  your  changes,  and  then 

write  “endif.”  By  setting  “My _ ” 

equ  “true”  in  the  “Conditionals”  section, 
you  insert  all  your  changes  into  the  as¬ 
sembled  code.  If  your  friend  wants  the 
original  code  back,  he  or  she  can  remove 

all  your  changes  by  setting  “My _ ” 

equ  “false.”  Unless  you  happen  to  have 
one  of  the  existing  conditional  systems, 
set  these  conditionals  equ  “false,”  add 
similar  lines  for  your  terminal  and  con¬ 
troller,  and  set  yours  equ  “true.”  Set 
“lineclr”  true  or  false  according  to 
whether  your  terminal  can  clear-to-end- 
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of-line  with  a  single  command. 

The  “Macro  Call”  section  has  been 
commented  out,  and  all  examples  of  its 
use  have  been  expanded  by  hand,  so  that 
you  can  use  a  simple  assembler  like  ASM. 
Ignore  it.  Under  “Console  Functions” 
comes  your  first  chance  to  say  “if  My- 
terminal.”  Set  as  many  of  the  variables  as 
your  terminal  uses  to  the  values  given  in 


your  manual.  Don’t  forget  the  “endif.” 
Check  the  ASCII  code  equates,  especially 
backspace,  for  compatibility  with  your 
terminal. 

In  “Floppy  Controller  Port  Equates,” 
you  tell  the  program  where  to  send  com¬ 
mands  for  the  disk  controller.  Set  up  a 
conditional  for  your  controller;  you  can 
probably  copy  these  addresses  directly 


from  your  BIOS  source,  if  you  have  it. 
Note  how  the  base  address  is  given  in 
absolute  numbers,  and  all  the  other  ad¬ 
dresses  are  given  as  offsets  from  the  base. 
Most  systems  with  a  1793  controller  chip 
will  have  these  same  offsets  from  what¬ 
ever  base  address  the  system  uses. 

In  the  “if  Dysan”  conditional,  “dma” 
is  a  port  address  where  commands  to  the 


is  .28  milli-inches  on  inner  tracks;  .57  milli-inches  on  outer  tracks. 


12  milli-inches 


Sample  A 


Sample  B 


(Recorded  data  -*  000000000000000  0)  (Recorded  data  ->  1010101010101010) 


Figure  1. 

The  actual  magnetic  pattern  on  an  8 -inch  diskette,  to  scale. 

The  black  lines  are  not  on  the  diskette.  There  are  no  prearranged  "boxer"  to  be  filled  in,  only  uniform  magnetic  particles.  When  you  write  on 
the  blank  diskette,  you  arrange  these  particles  in  alternating  stripes  of  "north"  and  "south"  poles  (the  light  and  dark  areas  in  the  figure).  It  is 
not  the  polarity  itself  but  the  change  in  polarity  that  is  significant.  Sample  A  is  a  two-byte  string  of  "0"  bits,  which  means  that  there  are  no 
(zero)  transitions  with  a  bit  space.  Sample  B  alternates  between  "1 "  and  "0”  bits;  a  transition  within  a  bit  space  is  read  as  a  "1 
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Figure  2. 


An  alternative  offset  track. 

Each  data  sector  is  128  bytes,  while  sector  IDs  are  31  bytes  and  sector  gaps  are  29  bytes  or  less.  The  track  header  is  73  bytes.  The  circular  track 
is  shown  here  stretched  out  straight  for  convenience  —  tracks  form  complete  circles  on  diskettes. 
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direct  memory  access  controller  are  sent. 
Each  time  this  controller  is  asked  to  read 
the  disk,  it  is  sent  an  address  in  memory 
at  which  to  begin  storing  what  is  read.  It 
reads  the  disk  and  puts  the  data  directly 
into  memory,  while  the  CPU  does  other 
tasks,  by  using  the  slivers  of  time  between 
CPU  memory  accesses.  In  my  CCS  condi¬ 
tional,  “dma”  is  a  memory  address  where 
a  pointer  to  a  memory  buffer  is  stored.  In 
this  non -dma  or  programmed  I/O  transfer 
system,  after  telling  the  controller  to  read 
the  disk,  the  CPU  must  be  ready  to  grab 
each  byte  as  it  is  read  and  to  move  it  into 
memory  before  the  next  byte  is  ready. 
The  CPU  looks  at  “dma”  to  find  out 
where  in  memory  to  begin  storing  the 
read  data.  Obviously,  the  CPU  cannot  do 
anything  else  while  it  is  busy  moving  in 
data;  in  fact,  to  keep  up  with  a  double¬ 
density  8 -inch  disk  it  must  run  at  least 
at  4  MHz. 

“Floppy  Controller  Commands”  is 
another  section  you  might  copy  from 
your  BIOS  source.  Command  “sdma” 


tells  the  Dysan  controller  to  begin  trans¬ 
ferring  data;  if  you  have  a  dma-type  con¬ 
troller,  it  should  have  a  similar  command. 
Variable  “fdelay”  is  used  in  the  “delay” 
routine,  where  time  is  being  carefully 
counted.  Instead  of  issuing  a  command  to 
the  controller  and  checking  to  see  if  it  is 
processed,  this  routine  dispenses  the  delay 
time  in  known  chunks  of  50  microsec¬ 
onds.  If  you  don’t  have  a  4  MHz  Z80,  and 
you  want  the  timing  routines  to  work, 
“fdelay”  and  the  “delay”  routine  will 
have  to  be  juggled  until  the  loop  takes  50 
microseconds.  “Indxbyt,”  “busybyt,” 
and  “drqbyt”  are  masks  that  select  the 
appropriate  bit  from  the  status  register  of 
the  controller  chip.  For  example,  if  the 
status  register  is  read,  and  the  logical 
“and”  function  is  done  with  “busybyt,” 
a  0  will  result  unless  the  bit  signifying 
“busy”  is  set  high.  A  bit-by-bit  explana¬ 
tion  of  status  register  contents  should  be 
available  in  your  controller  chip  data 
sheet.  The  other  variables  in  this  section 
go  directly  to  the  controller  chip  and  can 


be  determined  from  the  manufacturer’s 
data  sheet,  if  not  from  your  BIOS  source. 

In  “DDD  Diskette  Variables,”  the 
total  number  of  tracks  and  the  number  of 
sectors  per  track  in  your  chosen  format 
are  set.  Note  that  several  other  parameters 
are  defined  in  terms  of  sectors  and  need 
not  be  changed.  “Ref”  is  a  magic  number 
that  will  be  discussed  later  under  “Index 
Timing.”  Ignore  it  for  now.  Those  of  you 
with  nonstandard  CP/M  systems  will  have 
to  change  the  “org”  address.  Otherwise 
we’re  already  down  to  the  actual  program! 

Step  on  down  to  “Clear  Console  Dis¬ 
play”  —  the  code  in  between  should  run 
unchanged  on  any  CP/M  system.  If  your 
terminal,  like  the  Hazeltine,  needs  an 
extra  lead-in  byte  ahead  of  the  actual 
clear-screen  command,  you’ll  need  to  put 
in  an  “if  Myterminal”  here.  “Clear  Dis¬ 
play  Line”  has  two  conditionals:  one  for 
terminals  with  a  clear-to-end-of-line 
command,  which  is  active  if  “lineclr  equ 
true,”  and  another  that  prints  a  string  of 
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blanks  for  terminals  without  this  feature. 
If  you’ve  set  “lineclr”  true,  and  if  your 
terminal  needs  a  lead-in  byte  or  other 
special  treatment,  insert  an  “if  Mytermi- 
nal  AND  lineclr”  as  I  have  for  the  Hazel- 
tine.  Again,  in  “Print  String  of  Text,” 
insert  a  conditional  under  “textl”  for 
lead-in  type  terminals.  If  your  terminal 
should  need  the  row  position  sent  before 
the  column  position,  accomplish  that 
here  by  incrementing  the  HL  register  pair 
twice  after  the  position  cursor  command 
(to  get  the  row  position)  and  then  decre¬ 
menting  HL  to  get  back  to  the  column 
position.  This  code  section  assumes  that 
the  upper  left-hand  corner  of  your  screen 
is  called  0,0.  If  your  terminal  places  0,0 
somewhere  else,  you’ll  have  to  add  a 
constant  bias  to  the  coordinates  before 
you  send  them. 

“Index  Timing”  may  require  major 
changes.  In  the  Dysan  dma  system,  the 
command  “read  address”  is  sent  to  the 
dma  controller,  “start  dma”  is  sent,  and 
the  CPU  is  set  to  counting  the  time  until 
the  controller  is  finished  doing  its  direct 
memory  access.  If  you  have  a  dma-type 
controller,  you’ll  use  this  scheme  as  it  is. 
If  you  have  a  programmed  I/O  controller, 
the  CPU  cannot  transfer  data  and  count 
time  simultaneously.  My  solution,  in  the 
CCS  conditional,  is  to  sene  the  “read 
address”  command  and  immediately  set 
the  CPU  to  counting  time  until  “drq” 
comes  true.  When  the  first  byte  of  address 
data  is  ready  to  be  transferred  to  memory, 
the  disk  controller  sets  “drq”  true,  telling 
the  CPU  to  “come  and  get  it.”  The  CPU 
immediately  determines  (lhld  dma)  where 
to  put  the  byte,  reads  it  from  the  data 
port,  and  moves  it  to  memory.  It  incre¬ 
ments  the  memory  address  and  goes  after 
the  next  byte.  “Read  address”  reads  only 
six  bytes  of  data,  so  I  wrote  six  reads 
inline. 

Since  the  non-dma  CPU  only  counts 
time  before  the  data  transfer,  the  time 
counting  loop  after  that  code  is  for  the 
Dysan  controller  only.  But  because  the 
Dysan  dma  controller  counts  both  the 


time  from  the  “read  address”  command 
to  the  first  data  byte  and  the  time  needed 
to  transfer  six  bytes  of  data,  it  will  get  a 
longer  time  count.  This  is  where  “ref” 
comes  in.  “Ref”  is  a  magic  number  or, 
more  bluntly,  a  fudge  factor,  which 
makes  the  final  count  read  however  we 
want  it.  Since  “ref”  is  subtracted  from 
the  total  time  count,  the  non-dma  con¬ 
troller  will  require  a  smaller  “ref”  value 
than  the  dma  controller.  Dysan’s  value  is 
experimentally  set  with  their  Analog 
Alignment  Diskette,  whose  track  has  a 
standardized  200  microsecond  time  from 
index  hole  to  address  mark.  My  value  of 
24EH  is  estimated  to  make  my  DDD  also 
give  about  200  microseconds  on  my 
drives  —  hardly  a  precise  method,  but  a 
relative  measure  is  better  than  no  measure 
at  all. 

“Index  Timing”  is  the  first  section 
to  introduce  the  problem  of  time  count¬ 
ing.  You’ve  undoubtedly  noticed  that 
many  of  the  instructions  are  followed  by 
numbers  in  the  comment  field.  These 
numbers  give  the  execution  times  in 
microseconds  for  those  instructions  on  a 
4  MHz  Z80.  If  your  CPU  is  clocked  at  2 
MHz,  the  instructions  will  tak-*  twice  as 
long.  But  disk  reads  of  data  happen  at  the 
speed  of  the  moving  diskette,  regardless 
of  the  CPU  clock,  it  you  intend  to  prop¬ 
erly  adapt  t^is  routine  to  a  different 
clock  rate,  you  wili  have  to  manipulate 
not  only  the  timings  here,  but  also  the 
delay  provided  by  “delay”  "nder  “FDC 
Delay  to  Process  Commands”  and  the 
loop  count  “fdelay”  in  “Floppy  Con¬ 
troller  Commands.”  Unless  you  enjoy 
mathematical  puzzles,  I  suggest  you  join 
me  in  a  cut-and-try  fudge.  In  “Index  to 
Index  Timing”  and  its  “RPM  Timing 
Loop,”  no  disk  reads  are  involved,  only 
time  counting  between  index  pulses.  Here 
a  2  MHz  processor  should  get  exactly  half 
the  proper  time,  and  a  mathematical  cor¬ 
rection  is  reasonably  simple.  Translate 
the  instruction  times  into  their  corre¬ 
sponding  values  at  your  clock  speed,  and 
set  fewer  loop  passes  or  adjust  the  trailing 


“inx  d”  instructions  to  give  *he  required 
100  microsecond  loop. 

“Drive  Select”  is  your  chance  to  be 
original.  The  version  1.0  option  simply 
selects  one  drive  only.  My  CCS  option  can 
select  one  of  four  drives  connected  to  a 
CCS  2422  controller,  but  it  does  not  deal 
with  double-sided  drives.  The  code  down 
to  “jmp  select”  should  be  pretty  universal. 
After  that,  you’ll  have  to  determine  from 
your  manual  (or  crib  from  your  BIOS 
source)  the  codes  needed  to  select  drives 
under  your  controller  and  then  invent  a 
way  to  turn  “A,B,C,  or  D”  into  whatever 
codes  you  need.  If  you  need  to  select 
sides  on  a  double-sided  drive,  duplicate 
the  top  part  of  the  CCS  option  then  dis¬ 
play  a  “Which  Side?”  message,  translate 
the  response  into  the  proper  code,  and 
send  it  to  the  proper  port. 

In  the  “Read  Sector  Routine,”  we 
again  have  to  separate  dma  controllers 
from  non-dma  controllers.  With  a  dma 
controller,  just  issue  the  go  command  and 
check  to  see  when  the  status  register  says 
all  the  data  are  transferred.  With  a  pro¬ 
grammed  I/O  controller,  you’ll  have  to 
tell  the  CPU  every  step  to  take  to  get  the 
data  into  memory.  Under  “readl”  in  the 
CCS  option,  I  loaded  HL  with  the  memory 
destination  of  the  first  byte  and  initialized 
a  loop  counter.  Each  loop  through  the 
data  transfer  code  reads  four  bytes,  so  to 
read  an  8 -inch  single-density  sector  takes 
32  (20H)  loops.  Double-density  8-inch 
sectors  require  64  (40H)  loops.  This  rou¬ 
tine  can  probably  be  adapted  from  the 
disk  read  routine  in  your  BIOS.  You  could 
call  the  BIOS  routine,  but  that  would 
make  your  DDD  program  nonportable. 

“Program  Disk  Controller”  originally 
output  a  series  of  commands  to  a  dma 
controller,  reading  them  in  serial  form 
from  the  table  that  followed.  If  you  have 
a  dma  controller  that  needs  to  be  “primed” 
with  a  string  of  commands,  create  your 
own  conditional  table  and  adjust  “Bytes 
count  ”  for  the  number  of  bytes  you  need 
to  send.  Your  manual  should  explain  the 


procedure;  otherwise,  find  a  data  sheet  on 
the  actual  chip  used  or  copy  from  your 
BIOS.  Even  a  non-dma  controller  needs 
some  priming.  Mine  will  look  at  memory 
address  “dma”  (remember  “Floppy  Con¬ 
troller  Port  Equates”?)  and  expect  to 
find  the  address  of  “secbuf,”  a  memory 
buffer  to  move  data  to.  The  other  item 
needed  to  prime  it  for  a  disk  read  is  the 
setting  of  “autowait,”  a  function  of  the 
CCS  2422  controller  card  that  puts  my 
CPU  into  a  wait  state  from  the  time  it 
sends  a  disk  read  command  until  the  first 
byte  of  data  is  ready.  The  catch  is  that  to 
set  “autowait”  I  have  to  write  to  the 
same  port  that  does  disk  select;  thus  I 
save  the  bits  I  used  to  select  the  current 
disk  and  sent  them  here  with  a  double 
function. 

“Delay”  has  already  been  dealt  with 
(or  fudged),  so  unless  you’d  like  to  custo¬ 
mize  some  of  the  console  displays  or  mes¬ 
sages,  we’ve  reached  the  end  of  the  source 
code!  Run  it  through  your  assembler  and 
clean  up  any  trivial  errors,  and  the  program 
should  be  yours.  To  make  it  a  useful  tool, 
you’ll  need  to  create  a  “before”  picture 
of  your  drives’  operation.  Run  all  the 
tests  on  all  your  drives  and  write  down 
the  results.  There  are  no  “correct”  results 
for  these  tests;  however,  you’d  like  to  be 


able  to  read  as  many  sectors  as  possible 
and  to  have  your  readings  symmetrical 
around  the  center  of  a  properly  aligned 
track.  If  you  record  a  baseline  while  your 
drives  are  working,  you’ll  be  able  to  iden¬ 
tify  any  subsequent  changes  as  possible 
causes  of  new  malfunctions. 

Finally,  be  aware  that  flexible  disk¬ 
ettes,  including  the  DDD,  change  size  wiih 
temperature  and  humidity.  A  change  of 
18°F  can  move  the  outer  tracks  of  an 
8-inch  disk  up  to  1  milli-inch.  On  an 
extremely  humid  day,  the  outer  tracks 
may  “grow”  another  3  milli-inches.  If 
your  drives  are  in  a  poorly  ventilated 
enclosure  where  the  temperature  rises  to 
125°F,  that  alone  can  move  traks  7 
milli-inches  out  of  alignment.  Run  your 
baseline  tests  under  normal  conditions 
of  operation  after  your  system  is  well 
warmed  up,  and  be  sure  the  DDD  has 
had  time  to  acclimate  to  the  room  and 
to  the  temperature  inside  the  drive  you’re 
testing.  Proper  drive  alignment  once  the 
drives  are  packed  into  your  enclosure 
may  be  considerably  different  from  align¬ 
ment  in  the  open  on  a  test  bench. 

■■J 

( Listing  begins  below) 


Diagnostic  Diskette  Listing  (Text  begins  on  page  40) 


1 


j: 

4:  ; 
5s 

6s  5 
7s 

8s  ; 
9:  ; 
105 
lls  ; 
12s  ; 
13s  ; 
14s 
15s  : 
16s  ; 
17s  ; 
18s  : 
19s  ; 

20  s  ; 

21  s 


24  s  ; 
2Fs 


26 


34 


DIGITAL  DIAGNOSTIC  DISKETTE  tm  APPLICATION  PROGRAM 

BY  LOREN  AMELANG,  BON  24,  PHILO,  CA  95466  0024 

THIS  CODE  EXCERPTED  FROM  VERSION  1.1  CDDD1 1. ASM) 

'(THE  EXCERPT  DOES  NOT  INCLUDE  STEPPER  HYSTERESIS 

OR  INDEX  TIMING  CHECKS...,? 

This  document  contains  information  developed  by 
Dysan  Corporation  < Dysan}  and  is  furnished  for 
information  only. 

Dysan  makes  no  warranty  or  representation  < expressed 
o r  i m p 1 i ed  >  w i t  h  r es p e c t  to  t h e  acc u ra c y ,  com p 1 e t  e n ess 
or  usefulness  of  the  i nformation • contai ned  herein. 
Further  Dysan  assumes  no  responsibility  for  liability 
or  damase  of  any  kind  which  may  result  from  the  use 
of  the  information  contained  herein. 

THIS  PROGRAM  IS  IN  THE  PUBLIC  DOMAIN,  AND  MAY  BE 
FREELY  COPIED  AND  DISTRIBUTED 


*********  ******** 

USAGES 

To  use  this  pros  ram,  a  disital  alignment  disk  is  required. 

Yo u  may  p u r c has e  the  rerui r ed  "Disital  D i a s nos t i c  D iskette"  ( tm > 
directly  from  Dysan  Corporation.  Available  DDD(tm)  models  ares 

SIDES.’ . SINGLE  SI DED . DOUBLE  S I DED 

( Continued  on  page  50 ) 
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Diagnostic  Diskette  Listing  (Listing  continued,  text  begins  on  page  40) 


DENS I T V : . SI NGLE <FM)  DOUBLE < MFM ) ...  SI NGLE < FM )  DOUBLE < MFM ) 

SIZE  &  TP I s 


8" 

48 

TP  I 

808-180 

808-208 

808- 

300 

808-400 

5.  25" 

43 

TP  I 

508-180 

588-200 

508— 

300 

508-480 

5.  25" 

96 

TP  I 

506- 1 00 

506-200 

586- 

300 

•506—400 

5.  25  " 

100 

TP  I 

CALL  FOR 

AVAILABILITY 

CALL 

FOR 

AVAILABILITY 

PRICES 

:  Si  ns  1 e 

Sided  - 

$30.00  Doubl 

e  Sid ed  “ 

$40.  00 

Plus  appropriate  sales  taxes  and  shipping  costs 
Prices  a  nd  mod  els  subject  to  c  ha ns  e  wit  ho  u  t  no  t i c  e 


ORDERING:  Contact  your  local  Dysan  sales  Rep.  or  call 
I  ns  i  d  e  No  r  t  h  e  r  n  Cali  f  o  r  n  i  a :  <  4  OS'  >  988-3472 

Outside  Northern  California:  <800)  551-9080 


TECHNICAL  INFORMATION:  For  information  resardins  DDD<tm) 

applications  co n  ta  c t  Dy sa  n ' s 
CE  Division  TECH-LINE:  <488)734-1624 


***  ***********  *********************************  ***************** 
PROGRAM  SOURCE  CODE : 


wboot  eau  0 

bd  os  ea  u  5 


***** ***************** 
***  "CONDITIONALS"  *** 
********************** 


warm  boot  address 

Jump  address  for  bdos  call-; 


*7-“i 

i 

; 

C  ho  O  S  *5 

the  appropriate  assemble  time  options  for  your  system? 

73 

74 

75 

o  r  us  e 

this  space  to 

add  new  system  options. 

? 

t  r  u  e 

e<iu 

0f f ff h 

76 

false 

no  t  true 

1*’  f 

70 

1  u 

Dysan 

false  ; s  e  t 

this  true  for  Dysan  controller 

79 

CCS 

esu 

true  ?set 

this  true  for  CCS  2422  controller 

80 

81 

1  i  n  e  c  1  r 

e^u 

false  5  s  e  t 

pros  rammed  iAo  transfer,  etc. 
this  true  if  your  console  has 

oo 

'-‘jL. 

83 

Hazel 

e<iu 

false  .set 

a  c  1  ea  t —  to-  e  nd  -o  f  - 1  i  n  e  comma  rid 
t  h i s  true  f o  r  Haz  e 1 1 i n  e  1 500  t  e  rm i na 1 

84 

85 

Loren 

esu 

true  ‘set 

tresuirins  "lead-in"  to  commands) 
this  true  for  Loren’s  homebrew  terminal.. 

"ADD  CONDITIONAL  OPTIONS  FOR  YOUR  ENVIRONMENT  HERE.. 


*************************** 

***  "CONSOLE  FUNCTIONS"  *** 
*************************** 

;  The  followins  are  direct  console  command- 

■  which  can  be  altered  for  most  consoles. 


The  text  print  routine  must  be  altered 
if  "Row"  is  sent  before  "Column"  or 
bias  is  needed. 
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i  f 

Hazel 

version  1.  0 

ad  d  f  c  u  r 

eau 

17 

address  cursor  command 

clrfco 

eau 

28 

clear  to  fores  round  spac 

1 ead$i n 

eau 

126 

console  lead-in 

end$l n 

eau 
end  i  f 

15 

clear  to  end  of  line 

i  f 

Loren 

v  e  rs  i  o  n  1.1 

add T cur 

eau 

01 

address  cursor  command 

cl  rf co 

eau 
e  nd  i  f 

05 

c  1  ea  r  to  f o  r  es  r o  u  nd  s  F-a  c 

cr 

eau 

0dh 

carriase  return 

If 

eau 

04  h 

line  feed 

HV  C 

eau 

lBh 

escape 

bs 

eau 

y 

back  space 

bell 

eau 

a  ud i o  ale  r  t 

**+  "FLOPPY  CONTROLLER  PORT  EQUATES"  *** 
**************************************** 


127 

C  ha  ns  e 

the  f o 1 1 ow i ns  Po r t  ass i s  nm e  n  ts  f o r 

128 

Yo  u  r  s': 

s  t  em. 

129 

130 

"FDC" 

Acronym  Floppy 

Disk  Controller 

131 

f 

132 

133 

134 

FDC  po r  t  ass i s  nm  e  n  ts : 

if 

Dy  sa  n 

j  v  e  rs  i  o  n  1.0 

135 

fd  C 

ea  u 

0  f  S'H 

;  Base  port  address  FDC 

1 36 

f 

137 

cmd 

eau 

fd  c 

5  command  res. 

138 

stat 

eau 

fd  c 

•  status  res. 

139 

trk 

eau 

fdc+1 

?  track  res. 

140 

sec 

eau 

fdc+2 

;  sector  res. 

141 

data 

eau 

fd  c+3 

•  data  res. 

142 

dma 

eau 

fd  c+4 

;  Dma  controller 

143 

dsel 

eau 

fd  c+5 

5  drive  select 

144 

end  i  f 

145 

146 

if 

CCS 

■version  1.1 

147 

fd  c 

eau 

30H 

■  Base  port  address  FDC 

148 

149 

cmd 

eau 

fd  c 

;  command  res. 

150 

stat 

eau 

fd  c 

"  status  res. 

151 

trk 

eau 

fdc+1 

•  track  res. 

152 

sec 

eau 

fd  c+2 

;  sector  res. 

153 

d  a  ta 

eau 

fd  c+3 

?  data  res. 

154 

d  ma 

eau 

004CH 

; memory  address  of  pointer  to 

155 

f 

sector  buffer 

156 

dsel 

eau 

fd  c+4 

•  drive  select  port: 

157 

'output  BN  for  sinsle  density 

1 58 

;  FX  for  double  density 

159 

■  where  X  =  1  for  drive  A 

160 

■  2  for  drive  B 

161 

■  4  for  drive  C 

162 

■  S  for  drive  D 

163 

end  i  f 

************************************ 
***  "FLOPPY  CONTROLLER  COMMANDS"  *** 
************************************ 


169 

; 

These 

are  common 

to  mos  t  s 

y s  t  ems  us i ns  the  1 

170 

' 

sdma 

is  a  Dysan 

control  1 er 

comma  nd ..  i  s  no  r  ed 

171 

172 

cl  ear 

eau 

0d@h 

clear  FDC 

1 

sd  ni-i 

eau 

87  h 

Start  Dma  Transfer 

174 

rsec 

eau 

80  h 

read  sector 

175 

radd  r 

eau 

0c0h 

read  address 

(Continued  on  next  page ) 
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Diagnostic  Diskette  Listing  (Listing  continued,  text  begins  on  page  40) 


seek  eau 
restore  esu 
sdelay  eau 


•  seek  track 
;  home  Head(s) 

;  seek  delay  f las 


:f****#**+*:f*:+::f:f**.f**:f**:*:**:f:f***+jt:**** 

***  "FLOPPY  CONTROLLER  VARIABLES"  *** 
************************************* 


r  a  t  e  ea  u 
retry  eau 
fdelay  eau 


indxbyt  eau 
busy  by t  eau 
drsbyt  eau 


i  step  rate 
?  read  retries 
FDC  delay 

see  "delay"  routine  -  this  value  is  for 
4  Mhz.  Z-80;  adjust  here  or  in  "delay" 
to  suit  your  clock  and  processor. .. 
byte  in  status  res.  when  index  hole 
is  passins  sensor 

byte  in  status  res.  when  controller 
is  busy 

byte  in  status  res.  when  data  is 
waitins  to  be  read  by  the  computer 


******************************* 

***  "ODD  DISKETTE  EQUATES"  *** 

* * :fr  :f + * :*  *  :f  *  :f  *  *  *  +  :f + * + *  * # # * * *  +'  * * * 

;  Adjust  to  match  your  diskette  size  and  format. 


ttrk 

e^u 

76 

total  number  of  tracks 

sectors 

e^u 

26 

sectors  per  track 

> 

26  for  8“  DDD>  16  for  5.  25" 

1  nes 

e^u 

sectors+2 

;  last  nes.  sector  +2 

1  POS 

sectors+1 

j  last  pos.  sector  +2 

tsec 

e^u 

<sectorsx2>-l 

5 

centerins  test 

i  f 

Dy  sa  n 

reference  time  Csinsle  Den> 

ref 

e*u 

798 

J 

e  nd  i  f 

" 

< us  ed  in  " i nd  ex  7" > 

i  f 

CCS 

experimentally  determined... 

ref 

e=iu 
e  nd  i  t 

24eh 

5 

***  "MAIN  PROGRAM  LOOP"  *** 
*************************** 


o  r? 

10Oh 

lxi 

sp? stack 

? 

init  stack 

call 

select 

•* 

select  drive 

lxi 

spj stack 

reset  stack 

call 

els 

clear  display 

lxi 

h ,  m  e  1 

display  Menu. 

call 

text 

call 

ci 

$ 

selection? 

52 
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236 

CPI 

’  R’ 

"Radial" 

JZ 

rad  i  a  1 

238 

cpi 

’  A  ’’ 

"Azimuth" 

239 

Jz 

azimuth 

240 

CPI 

’  C' 

"Centeri ns " 

241 

Jz 

center 

242 

cpi 

’H’ 

"Hysteresis" 

243 

?  Jz 

hyster 

244 

CPI 

’S’ 

"RPM" 

245 

Jz 

rpm 

246 

CPI 

’  I  ’ 

" I nd ex" 

247 

J  Jz 

i  nd  ex 

248 

CPI 

’D’ 

“Drive  Select" 

249 

J  nz 

ex 

250 

call 

select 

251 

Jrnp 

ma  i  n 

new  drive  selected  -  set 

option 

252 

253 

ex:  cpi 

’E’ 

f 

"Exit  to  DOS" 

254 

Jz 

exi  t 

255 

mui 

a» bel 1 

Not  valid 

256 

call 

CO 

257 

Jmp 

main 

f 

try  as  a  in. .. 

258 

259 

260 

******##+****#*#*#**** 

261 

***  "  EXIT  TO 

DOS"  *** 

262 

263 

264 

exi  t: 

265 

call 

els 

J 

clear  display 

• 

266 

Jmp 

wboot 

267 

268 

*****  ******************** 

269 

+**  “CONSOLE 

STATUS"  *** 

270 

**.***************#******* 

271 

272 

;  returns  with  zero 

status 

flas  set. 

jL  f  •_< 

274 

cstat: 

275 

p  us  h 

h 

5 

sav e  all  r  es  i  s  t  e  r s 

276 

push 

d 

277 

push 

b 

278 

mvi 

c,  11 

j 

BDOS  console  status- 

279 

call 

bdos 

; 

function  call  added  for 

VI.  1 

280 

POP 

b 

281 

POP 

d 

-•o') 

POP 

h 

283 

ora 

a 

284 

ret 

285 

286 

*****•*.**.****.*********** 

287 

***  "CONSOLE 

INPUT"  *** 

288 

****#***********.******* 

289 

* 

298 

;  Returns  character 

in  "A" 

res. 

291 

ci : 

292 

p  us  h 

h 

5 

Save  all  resisters 

293 

p  us  h 

d 

294 

push 

b 

295 

mu  i 

Cj  1 

; 

BDOS  co  nso 1 e  input 

296 

call 

bdos 

function  call  added  for 

VI.  1 

297 

PO  P 

b 

298 

POP 

d 

299 

POP 

h 

300 

CPI 

es  c 

Exi  t? 

301 

J  z 

ma  i  n 

YES ! 

302 

cpi 

’a’ 

convert  to  upper  case 

303 

rc 

only. . . 

304 

CPI 

’  C’ 

(Continued  on  next  page) 
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Diagnostic  Diskette  Listing  (Listing  continued,  text  begins  on  page  40) 


305 

rnc 

306 

ani 

,A,+1 

307 

ret 

308 

309 

310 

311 

**#  "CONSOLE 

OUTPUT"  *** 

312 

313 

; 

A"  res. 

314 

;  Enter  with  character  in 

315 

316 

CO ! 

317 

p  us  h 

PSW 

save  all  resisters 

^  l  y 

p  us  h 

h 

■ 

9 

319 

rush 

d 

320 

push 

b 

321 

mov 
mv  i 

e>  a 
c  ?  6 

Pass  char  in  "E"  re 
BDOS  direct  console 

323 

call 

bdos 

function  call  added 

324 

POP 

b 

325 

POP 

d 

326 

POP 

h 

o2  r 

POP 

PSW 

328 

ret 

330 

331 

*#***#♦#####***###*#******#**** 

***  "INPUT  TRACK  LOCATIONS"  *** 

TTT 

****#«:Mc**#**#**#***********### 

;  Input  track  locations  for 

Radial 

336 

;  Hysteresis. Centeri ns  and 

Index  tests. 

337 

.  "B" 

contents  Upper  Limit 

upon  entry. 

338 

339 

i npftrk! 

340 

cal  1 

els 

m 

7 

cl  ear  display. . . 

341 

cal  1 

text 

342 

; 

343 

i np$trkl : 

344 

call 

ci 

a 

9 

wai ti ns. . . 

345 

crop 

b 

? 

within  limits? 

346 

J  n  c 

i np#trk2 

J 

no.  •  a 

347 

sui 

•’A’ 

348 

J  c 

i np#trk2 

7 

try  asain 

349 

1  hid 

temp 

5 

table  pointer 

350 

mo  i 

d,0 

351 

mow 

e?  a 

352 

dad 

d 

add  offset 

353 

mow 

a?  m 

load  track 

354 

Jmp 

track 

seek  to  track 

355 

5 

356 

inp*trk2: 

357 

mwi 

a>  bell 

7 

alert 

358 

call 

CO 

359 

Jr np 

i np#trkl 

a 

7 

try  asain... 

360 

361 

362 

***  "RADIAL 

AND  HYSTERESIS  TRACK 

LOCATIONS"  *** 

363 

*  * #  *  *  *  *  *  * :+:  * * * * # * if * *  *  *  * #* *  *  *  *  *  4  #  *  # * 4 * * * + * *  * * *  *  * 

364 

365 

rh$tbl 
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?  Note:  some  Dysan  spec  sheets  list  track  5  rather 

:  than  3  as  an  index  track  -  my  Revision  A  DDD  definitely 

?  uses  track  3. . .  LA. 

db  38 

db  41 

db  70 

db  73 

if*:*:**:*  if****:*;**  $$$$ 

***  "INDEX  TRACK  TABLE"  +** 

*****************  *  *****  * * *  * 

ix*tbl: 


*  * * * + :f  *  *  :f  if  :*  :f  :f  *  *  *  :f  *  *  * + *  :f  *  * 

**  "CENTERING  TRACKS"  *** 
************************* 

cen^tbl : 


♦♦a***:*###*###**#**#*#*###***** 
***  "PRINT  DECIMAL  NUMBERS"  *** 
******************************* 


398 

• 

Enter 

with  number 

to  be  printed  in 

399 

5 

’  DE’ 

res. 

400 

401 

p  n  um  s 

402 

push 

h 

•  Setup  Stack 

403 

lxi 

h,  10 

•  Termi  nator. . . 

404 

push 

h 

405 

p  us  h 

h 

406 

5 

407 

pr il : 

Divide  N  um  b  e  r  By  <  1 0  > 

408 

call 

d  ivl6 

409 

mov 

a  r  d 

;  Check  result 

410 

ora 

e 

;  =  0 

411 

J  z 

pn2 

412 

xthl 

413 

dcr 

1 

414 

p  u=-  h 

h 

415 

lxi 

h,  10 

416 

Jmp 

pnl 

■  D  i  v  i  d  e  As  a  i  n 

417 

" 

418 

fh'2 • 

;  Display  Values 

419 

PO  P 

d 

420 

mov 

e,  1 

421 

? 

422 

p  n3: 

;  Check  f o  r  T  e  rm i na to r  <  1 0 ) 

423 

mov 

a>  e 

424 

cpi 

10 

425 

POP 

d 

S  N  ex  t  d  i  s  i  t 

426 

rz 

(Continued  on  next  page) 
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Diagnostic  Diskette  Listing 

(Listing  continued,  text  begins  on  page  40) 


427: 
428 : 
429: 
430: 
431: 
432: 
433: 
434: 
435: 
436: 
437: 
438 : 
439: 
440: 
441: 
442: 
443: 
444: 
445: 
446: 
447: 
448: 
449: 
450: 
451: 
452: 
453: 
454: 
455: 
456: 
457: 
458: 
459: 
460: 
461: 
462: 
463: 
464: 
465: 


acji  >0J  ;  Add  ascii  Bias 

call  co 

dm  f-  fh3 


***  "16  BIT  SUBTRACT I OH"  *** 
**+*********+#**+*+##*+4::f*** 


subd  e: 


Subtract  "DE"  from  "HL" 

moo  a  > 1 

sub  e 

moo  1 >  a 

moo  a?  h 

sbb  d 

moo  h>  a 

ret 


* * *  *  *++*:+:  * # * # *  # # * # * # # #  #  * * * * *  * 
***  “COMPARE  "DE"  TO  "HL"  *** 
***************************** 


d  ehl  •' 


mo'v1 

a  y 

1 

cmp 

e 

rnz 

mov 

d  y 

h 

crop 

d 

ret 

compare  "E"  to  "L" 
;  If  not  zero  return 


♦a******************************** 
***  "16/24  BIT  DIVIDE  ROUTINE"  +** 

it********************************* 

?  Dioide  "HL"  by  "DE" 


466: 

y 

467: 

468: 

diol6: 

469: 

x  ra 

a 

470: 

; 

471: 

dio24: 

472: 

sta 

msb 

4 1  o : 

shld 

rnsbl 

474: 

lxi 

h » ms  b2 

475: 

mui 

m> 24+1 

476: 

lxi 

b,0 

477 : 
478: 

dio25: 

p  u=  h 

b 

479: 

roov 

a?  e 

480: 

ral 

481 : 

MOM 

e>  a 

482: 

mov 

a»d 

483  • 

ral 

484: 

mov-* 

df  a 

485: 

Ida 

msb 

486: 

ral 

487: 

sta 

msb 

488: 

d  cr 

m 

489: 

POP 

h 

490: 

rz 

;  optional  16  bit  dioide 

’  Normal  24  bit  dioide 


Dr.  Dobb’s  Journal,  December  1983 

750 


491 

492 

493 

494 

495 

496 

497 

498 

499 

500 

501 

502 

503 

504 

505 

506 

507 

508 

509 

510 

511 

512 

513 

514 

515 

516 

517 
513 

519 

520 

521 

522 

523 

524 

525 

526 

527 

528 

529 

530 

531 

532 

533 

534 

535 

536 

537 
538: 
539! 
540; 

541 

542 

543 

544 

545 

546 

547 

548 

549 

550 

551 

552 

553 

554 


mv  l 

a.  0 

aci 

0 

did 

h 

mov 

b»  h 

add 

1 

1  hid 

msbl 

sub 

1 

moo 

Cj  a 

moo 

a.,  b 

sbb 

h 

moo 

b.>  a 

p  us  h 

b 

J  nc 

d  i  v26 

dad 

xthl 

b 

di'-'26: 


1x1 

h>  msb2 

cmc 

J  rii  p 

div25 

f.fjf.f  :f.f:ff  f  f:ff  :ff  :ff*f  :f:f:ff:f  :f:f:f:f  f:f:f 

***  "CLEAR  CONSOLE  D I SLAY"  *** 


;  Clear 

console  to  foreground  spaces. 

els: 

i  f 

Hazel 

mu  i 

a  7 1 eadSi n 

?  1 ead  i  n 

call 
end  i  f 

CO 

mui 

a  7  c  1  rS  co  5 

clear  to  foreground 

J  m  f 

CO 

***m*********************'** 

***  "CLEAR  DISPLAY  LINE"  *** 

:f\>::f:f  *f  :f  *:f  .f  :f:f  :f:f  :f  f  :f  if  :f  f  S' f:f  f"f'f+:f 

cl i ne: 

i  f 

1  i  n  e  c  1  r 

mui 

a  7  0 

■  star tins  column 

sta 

co  1  um  n 

lxi 

h> sets cur 

"  set  cursor 

call 
end  i  f 

text 

if 

Hazel  AND  lineclr 

mu  i 

a? 1 eadSi n 

;  lead  in  byte 

call 
e  nd  i  f 

CO 

i  f 

1  i  n  e  c  1  r 

mui 

i,  endSl  n 

;  clear  to  end  of 

call 
end  i  f 

CO 

i  f 

HOT  lineclr 

mui 

a,  11 

•  star tins  column 

sta 

co  1  um  n 

lxi 

h  7  sets cur 

’  set  cursor 

(Continued  on  next  page) 
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555 

556 

557 

558 

559 
568 

561 

562 

563 

564 

565 

566 

567 

568 

569 

570 

571 

572 

573 

574 

575 

576 

577 

578 

579 

580 

581 

582 
5tf,> 

584 

585 

586 

587 

588 

589 

590 

591 

592 

593 

594 

595 

596 

597 

598 

599 

600 
601 
602 


call  text  x  ..  . 

lxi  h» blanks  ; address  or  a  strins  or  So  blanks... 

call  text 

end  i  f 

ret 

************************* 

***  "FATAL  ERROR  MSG"  *** 

********+**++**+**+'*+*#*♦ 

fatal  J 


i  f 

1 i necl r 

line 

call 
end  i  f 

cline 

;  clear 

mvi 

a,  30 

;  column 

position 

sta 

col umn 

lxi 

h, settcur 

call 

text 

lxi 

h»me2 

;  Fatal 

error  mss 

call 

ret 

text 

*****++:f*+**+*+*+*****+*+'***** 

***  "PRINT  STRING  OF  TEXT"  *** 

****************************** 

;  Enter  with  "HL"  pointins  to  text  strins , 

•  terminate  strins  with  Null. 

!  Direction  cursor  position  is  used  for  displays. 

?  The  value  <-l)  at  the  start  of  strins  indicates 

?  to  this  routine 

•  that  column  and  row  position  will  follow. 

;  This  format  does  not  necessarily  so  out  to 

;  you r  terminal.  If  your  terminal  needs  row  sent  before  column? 

or  a  constant  bias  added  (0,0  is  not  the  upper  left 
corner  of  the  screen)?  you’ll  have  to  invent  code 
;  within  this  routine  to  accomplish  that. 

•  This  is  the  internal  representation  format: 

;  db  -1,50, 10, ’NOW  IS  THE  TIME’ 

■  AAA 

•  !  !  !_Row  position  (add  bias  if  needed) 

;  !  '-Column  position  (add  bias  if  needed) 

;  !_Flas  (send  console  lead-in  sequence. 


603 

604 

text: 

60S 

mou 

a,  m 

606 

ora 

a 

607 

rz 

60S 

cpi 

(-1)  AND  0FFH 

609 

610 

Jz 

textl 

611 

i  nx 

h 

612 

call 

CO 

613 

Jmp 

text 

614. 

; 

615- 

textl : 

616: 

i  nx 

h 

? 

617: 

618: 

i  f 

Hazel 

619: 

mol 

a  ?  1  ead  t  i  n 

load  char, 
e nd  of  s t r i ns ? 
y  es 

position  cursor? 

"and  offh"  added  for  ASM  compatibility 
y  es 

next  char, 
output 


move  passed  command 


lead  ins  for  console 
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620 

call 

CO 

; 

i  ssue- 

621 

e  nd  i  f 

622 

623 

mo  i 

a.-  addfcur 

5 

address  cursor 

624 

cal  1 

CO 

625 

moo 

a?  m 

5 

col  umn  posi  tion. . . 

626 

i  nx 

h 

627 

call 

CO 

628 

moo 

a?  m 

y 

row  position 

629 

call 

CO 

630 

i  nx 

h 

631 

Jriftp 

t  ex  t 

632 

t-  f- f- -f-  f-  f-  f-  f- 1-  *  f-  f  + + ♦ + ♦  *  *  *  * 

634 

***  "CENTERING 

CHECK"  *** 

635 

636 

66  i 

* 

633 

■  Centering  test  requires 

the  FDC  to  read 

639 

;  all  the 

sectors  before 

diskette  centerin'? 

640 

;  is  cons 

ider  OK. 

641 

642 

center! 

643 

lxi 

h,  cenf tbl 

; 

track  table 

644 

shld 

temp 

645 

lxi 

h,  me9 

; 

tracks  with 

646 

mo  i 

b,  ’D’ 

" 

1  imi  t 

647 

call 

inpf trk 

seek  t  ra c  k 

648 

call 

els 

; 

clear  display 

649 

lxi 

h  >  m  e  1 0 

" 

centerins  ms?. 

65u 

call 

text 

651 

lxi 

h  >  m  e  1 5 

; 

frame 

652 

call 

text 

653 

lxi 

h>  mel  1 

; 

New  track  ms? 

654 

call 

text 

655 

• 

656 

c  e  n  t  e  r  1 : 

read  centerin?  tra 

657 

call 

rdf trk 

• 

658 

mo  i 

a,  10 

■ 

set  row  position 

659 

st  a 

row 

660 

J  c 

c  e  n  t  e r3 

fatal  error.. 

661 

662 

i  f 

1 i necl r 

clear  line 

663 

call 

cl  i  ne 

" 

664 

e  nd  i  f 

665 

set  cursor... 

666 

mo  i 

a>  38 

y 

667 

sta 

co  1  urn  n 

y 

column  position 

668 

lxi 

h>  setf cur 

669 

cal  1 

t  ex  t 

must  =  O 

670 

Ida 

d  i  f  f 

■ 

67 1 

ora 

a 

672 

lxi 

h m  e3 

; 

"RE-CLAMP  DISKETTE 

673 

J  nz 

c  e  n  t  e  r2 

674 

moo 

a  r  c 

675 

cpi 

tsec 

? 

all  sec  read? 

676 

J  nz 

c  e  n  t  e  r2 

677 

lxi 

h  >  m  e4 

" 

"CENTERING  OK" 

67b' 

; 

679 

center2s 

680 

call 

text 

681 

call 

cstat 

! 

abort ? 

682 

Jz 

centerl 

683 

call 

Cl 

684 

cpi 

?  y 

* 

new  track? 

(Continued  on  next  page) 
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685 

J  nz 

centerl 

5 

no.  .  . 

686 

J  m  f 

center 

5 

y  es. . 

687 

■ 

y 

688 

c  e  n  t  e r3 s 

fatal  error 

689 

call 

fatal 

? 

699 

J  m  p 

centerZ' 

691 

692 

693 

**********•******+**#******+***+** 

694 

***  "AZIMUTH 

ALIGNMENT  CHECK" 

*** 

695 

##*#***#*###*** ****************** 

696 

697 

azimuths 

698 

call 

els 

5 

cl  ear  display. . . 

699 

mvi 

■i  J  f  6 

> 

seek  to  azimuth  track 

700 

call 

track 

" 

move. . . 

701 

lxi 

h>  mel2 

type  of  test  ms? 

702 

call 

t  ex  t 

frame 

703 

lxi 

h ,  m  e  1 5 

5 

704 

call 

text 

705 

; 

706 

az  i  m  u  t  h  1  s 

707 

lxi 

h j aziftab 

j 

set  translation  table 

70S 

=  hid 

xpoi nt 

pointers 

709 

shld 

y  po i n  t 

710 

call 

rdftrk 

" 

read  azimuth  track- 

711 

my  l 

a?  10 

; 

set  row  position 

712 

sta 

row 

713 

J  c 

azimuth3 

; 

fatal  error. . . 

714 

715 

i  f 

1  i  n  e  c  1  r 

716 

call 

cl  i  ne 

clear  line 

717 

end  i  f 

713 

719 

my  i 

a,  20 

■ 

Display  nesative  ansle 

720 

sta 

col umn 

721 

lxi 

h?  sets cur 

" 

set  cursor 

call 

text 

723 

mvi 

a?  ■ 

; 

direction  of  ansle 

724 

cal  1 

CO 

5 

output. . . 

725 

riioi 

a,’  ’ 

" 

space 

726 

call 

CO 

r  jL  r 

1  hid 

y  po  i  n  t 

5 

translation 

728 

moo 

e>  m 

? 

data  nesative. . . 

729 

mvi 

d  ,  0 

730 

call 

pnurn 

y 

display 

731 

lxi 

h  .•  m  e5 

a 

f 

print  minutes 

“7T*? 

call 

text 

733 

mvi 

a- 45 

J 

Display  Positive  ansle 

734 

sta 

co  1  urn  n 

735 

lxi 

h>  set$ cur 

736 

call 

t  ex  t 

737 

mvi 

a, 7  +’ 

5 

direction  of  ansle 

738 

call 

CO 

? 

output... 

739 

mv  i 

a>  7  7 

• 

y 

space 

740 

call 

CO 

741 

1  hid 

xpoi nt 

| 

t  ra  ns  1  a  t  i  o  n 

742 

mov 

e>  m 

; 

data  positive.. 

743 

mvi 

d,0 

744 

cal  1 

pnurn 

> 

display 

745 

lxi 

h>  me5 

; 

print  minutes 

746 

call 

text 

747 

5 
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748s  azimuth2: 


749: 

call 

cstat 

abort? 

750 : 

J  z 

azimuthl 

751: 

call 

ci  .: 

test... 

752: 

J  m  p 

azimuthl  ; 

no. . 

753: 

754: 

5  Fatal 

error  Has  occurred 

755: 

756: 

757: 

> 

azimuthS: 

call 

fatal  * 

fatal  read  error 

758: 

JmF 

azimuth2 

759: 
760: 
761 : 

******************************** 

762: 

***  "RADIAL  ALIGNMENT  CHECK"  *** 

763: 

******************************** 

764: 

765: 

766: 

76.7: 

rad ial : 

lxi 

h>  rh$tbl  ’ 

table  pointer 

768: 

shld 

t  em  p 

769: 

lxi 

h>me7  * 

track  display.. 

770 : 

mu  l 

b,’G7  ? 

1  inn  t 

771 : 

call 

inpTtrk  ? 

select  track  and  seek 

r  f'  a-  « 

ca  1 1 

els 

i- 1'  3 : 

lxi 

h  ?  m  eS'  j 

pri nt  scale... 

77 4 : 

call 

t  ex  t 

775: 

lxi 

h.-mell  5 

Space  bar  mss 

776: 

call 

text 

i'  f  r  « 

778: 

779: 

780: 

? 

rad i a 1 1 : 

lxi 

h> radfpos  ; 

radial  positive 

781: 

shld 

x point  5 

cursor  table 

732: 

783: 

lxi 

h»  radTnes  ? 

radial  nesative 

784: 

shld 

y point  ? 

cursor  table 

785: 

786: 

call 

rdftrk  : 

read  radial  track 

7Q7  • 
i  Or  ■ 

mu  i 

a.- 11  5 

set  row  position 

700  ■ 
i  «_*o  • 

sta 

row 

-?  |-|  Q  m 
i  <_■  7  • 

Jc 

radial4  ! 

Fatal  error  has  occurred 

790: 

call 

cline 

clear  line  (1> 

791: 

Ida 

row 

792: 

push 

PSW 

793: 

i  nr 

a  ' 

clear  line  <2) 

794: 

S  t  A 

row 

795: 

call 

cl  i  ne 

796: 

POP 

PSW  ? 

reset  line  position 

797: 

sta 

row 

798: 

1  hid 

y  po i  n  t  ? 

n  es  a  t  i  v  e 

7QO  • 

I  77' 

moy 

a>  m 

800: 

sta 

co  1  urn  n  S 

position  cursor 

801 : 

mou 

b>  a 

802: 

lxi 

h>  setfeur 

803: 

call 

t  ex  t 

804: 

mvi 

J  AJ  • 

a  ?  ? 

set  pointer 

80S: 

call 

CO 

806: 

1  hid 

xpoi nt 

807 : 

moM 

a  ?  m  * 

pos i t i v e  pos i t i o n 

808: 

sta 

co  1  urn  n 

809: 

mo',-' 

Cj  a  ; 

save  cursor  position 

810: 

lxi 

h>set$cur  ' 

set  cursor 

64 
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829 

830 

831 


834 

835 

836 

837 

838 

839 

840 

841 

842  i 
843: 
844: 

845 

846 
347 

843 

849 

850 

851 

852 
853' 


OSS' ' 

856 
85 11' 
858 
859: 
860 
861 
862 
363 
364: 
865  i 


lxi  h>set$cur 

call  text 

moo  a.-  c 

sub  b 

dcr  a 

moo  b  ?  a 

moi  a>  ’  !  ’ 

ca 11  co 

rad i a 12: 

moi  a 

ca  1 1  co 

dcr  b 

Jnz  radial2 

mol  a> '  !  ’ 

call  co 

rad ial3: 

call  cstat 

■jz  rad  i  all 

call  ci 

cpi  '  ' 

Jnz  rad  tail 

Jmp  radial 

:f  *  ***** + + :*  *  :f + :f  .+  :f  :f  :f  :f  *  *  :f * *  *  :f  * 

***  "FATAL  RADIAL  ERROR"  *+* 

** :*  :f  :f  :f * + *  * :+  :f  ,f  :f * :f  :f  *  :*  :f  :f  :f' # *  :f f # 

radia!4: 


if 

1 i necl r 

cal  1 

cl  i  ne 

Ida 

row 

inr 

a 

sta 

row 

call 
endi  f 

cl  i  ne 

;  position  cursor 


;  line  lensth 
;  less  <1> 

5  pointer... 


'  Jointins  line 
;  line  lensth  -1 


•  check  for  abort 
read  asain 
;  new  track? 

;  no. . . 

5  new  track. . . 


5  clear  display 
‘  next  line 
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866 

867 

call 

fatal 

■ 

fatal  read  error 

868 

J  rn  f 

rad i a 1 3 

; 

abort? 

869 

870 

871 

872 

*#* 

"CHECK  SPINDLE  SPEED"  *** 

077 

87  4 

J 

875 

y 

All  tiftu ns  is  based  on 

4m hz  Z80  Cpu 

876 

! 

377 

rprn: 

37  3 

call 

els 

" 

clear  display 

879 

lxi 

h  >  m  e  1 9 

; 

test  performed 

880 

call 

text 

881 

lxi 

h..  melS 

; 

frame. . . 

337 

call 

text 

33%1< 

mu  i 

a..  10 

; 

set  row 

oo  -1 

007 

sta 

row 

OOC 

333 

rpml 

: 

887 

call 

rpm2 

* 

compute  time  in  100 us 
i ncrements 

888 

shld 

t  ern  p 

; 

store  count 

889 

890 

i  f 

1 i necl r 

391 

call 

cline 

; 

clear  line 

89 

end  i  f 

393 

894 

mv  i 

a,  19 

; 

set  cursor 

895 

sta 

col umn 

896 

1  x  i 

h,  set# cur 

897 

call 

t  ex  t 

fiQC; 

1  hid 
x  c  It? 

t  ern  p 

899 

• 

convert  to  milliseconds 

900 

lxi 

h,  10 

991 

call 

d  i  v  1 6 

902 

push 

h 

; 

Save  remainder 

903 

call 

pnum 

904 

rnui 

; 

decimal  point 

905 

call 

CO 

'906 

POP 

h 

907 

xchs 

908 

call 

p  n  urn 

; 

fraction 

909 

lxi 

h  >  tit  e20 

; 

milliseconds  mss 

910 

call 

t  ex  t 

911 

mu  i 

a,  50 

912 

•=•  ta 

col  urnn 

913 

lxi 

hr  set# cur 

914 

call 

text 

(Continued  on  next  page) 
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915: 

1  hid 

temp  5  concert  to  RPM 

916: 

mol 

a, 9  ;  divide  By  600.000 

917: 

1x1 

d >  27c0h 

918: 

.-all 

div24 

919: 

push 

h  ?  r  ema i nd e  r 

920: 

call 

p  n  urn 

921: 

mvi 

a.’.’  >  fraction 

922 : 

call 

CO 

923: 

POP 

h 

924: 

xchs 

925: 

call 

pnurn 

926: 

lxi 

h.-me21  ?  rpm  ms? 

927: 

cal  1 

text 

928: 

cal  1 

cstat  >  abort? 

929: 

Jz 

rpml  No.. 

930: 

call 

ci  J  Esc  key? 

931 : 

Jrnp 

rpml  *  No. . 

932 : 

933: 

934: 

935: 

*** 

INDEX  TO 

INDEX  TIMING"  **» 

936 : 

****##***##*#**#  #*##*##***#**** 

937: 

938: 

939: 

? 

With  4 

Mhz.  Z-80, 

940: 

r  e  t  u  r  n 

s  time  in  1@0  Us  increments  to  caller 

941: 

f 

in  "HL 

"  ress. 

942 : 

943: 

rp  m2: 

944 : 

call 

c 1 p  e  nd  !  Clear  pe nd i ns  comma  nd  s 

945: 

lxi 

h> 0  j  Clear  Counter 

946* : 

r  pm3 : 

947: 

i  n 

stat  5  Loop  Until  Index 

948: 

ani 

2  5  Mask  All  But  Index  Bit 

949: 

J  nz 

r  pm3  :  No  I nd  ex 

950: 

r  fiyi4: 

951: 

i  n 

stat  j  if  Index... 

952: 

ani 

2  j  Wait  for  No  Index 

953: 

Jz 

rpm4  In  Index  Hole 

954: 

955: 

• 

f 

Add  index  hole  to  count 

956: 

r  pm5 : 

957: 

call 

rpm7  ?  4. 25 

958: 

i  n 

stat  5  2.75 

959  • 

ani 

2  5  1.  75 

960: 

J  nz 

rpmS  :  2.  50 

961 : 

;  Total  =  11.25 

962: 

; 

Count 

until  next  Index 

963: 

964: 

rpm6: 

965: 

call 

rpm7  ’  4.25 

966: 

in 

stat  5  2.  75 

96  r : 

ani 

2  ?  1.75 

968: 

Jz 

rpm6  :  2.  50 

969: 

ret 

5  total  =  11.25 

970: 

971 : 

972: 

***  " 

RPM  TIMING  LOOP"  *** 

973: 

*  *  *  *  :f  *  * * * * + *  :f * +' * + 

974: 

J 

975: 

; 

The  loop  time  must  be  adjusted  for  100us 

976: 

5 

increments  at  your  clock  speed  with  your  process 

977: 

y 

978: 

y 

note: 

"RPMS  or  RPM6"  loop  time  must  be  counted 

979: 

y 

980: 

981 : 

rpm?s 

982: 

i  nx 

h  ?  1.50 

66 

758 


Dr.  Dobb’s  Journal,  December  1983 


983 

mv  i 

a,  22 

1.  75 

984 

y 

985 

r  pm8 : 

98b 

dcr 

a 

1.00  <22  *  1.00)  =  22  Usee 

987 

J  nz 

rpmS 

2.50  <22  *  2.50)  =  55  Usee 

988 

i  nx 

d 

1.  50 

989 

i  nx 

d 

1.  50 

990 

i  nx 

d 

1.  50 

991 

i  nx 

d 

1.  50 

992 

ret 

2.  50 

993 

total  =  88.  75 

994 

995 

996 

997 

**+  "READ  DDC 

TRACK"  *** 

998 

***:****+#***+•*.+ ********* 

999 

: 

1000 

; 

Att: 

Main  read  routine  f> 

:< r  program. 

1  002 

5 

1003 

y 

Reids 

the  Positive  and  Negative  offset 

1004 

; 

sectors  arid  returns  pointers  to  the 

1005 

y 

trans 

la t ion  tables  set  b'. 

caller. 

1006 

; 

1007 

1008 

r  d  $  t  r  k  s 

1009 

MV  I 

Aj7  ; Upper  case  code  adds  a  simple  display  of 

1010 

5  last  sector  read  <  +  £  -)»  sivins 

1011 

;  ?  and  ®  if  first  sectors  fail 

1012 

;  a 

ind  A  thru  Z  representing  the  26 

1013 

• 

'ossible  sectors  on  an  8"  disk 

1014 

•  or  A  thru  F'  for  a  5.25"  disk 

1015 

STA 

ROW 

1 0 1 6 

MV  I 

A,  39 

1017 

STA 

COLUMN 

1018 

LX  I 

Hi  SET f CUR 

1019 

CALL 

TEXT 

1020 

mv  i 

Cl  IPOS 

last  sector 

1021 

mv  i 

a  y  1 

besinnins  sector  positive 

1022 

call 

rdfsec 

r ead  pos i t i ve  of f s e ts 

1023 

ADI 

3  eH  it  ra  ns  1 

ite  sector  #  to  alpha  code 

1024 

CALL 

CO  !  displa1 

on  console  ♦r' 

1025 

SUI 

3eH  i  return 

to  sector  #  #/ 

1 026 

CPi 

1 

unable  to  read 

1027 

.IT 

rd$trk2 

first  sec? 

1028 

sta 

d  i  f  f 

store  last  sector  tested 

1029 

mv  i 

Ci  1  nes 

1030 

mvi 

a  9  2 

be? i uni  ns  sector  nesative 

1031 

call 

r dfsec 

read  negative  offsets 

1032 

ADI 

3eH 

1033 

CALL 

CO 

1034 

SUI 

3eH 

1035 

cp  i 

fatal  error? 

1036 

Jz 

rdftrk2 

set  error  f las 

1037 

; 

1038 

y 

Positive  sector  Translation 

1039 

“ 

1040 

Ida 

diff 

1041 

i  nr 

a 

add.  sector  Hum. 

1042 

SUI 

4 

1043 

ra  r 

divide  by  two 

1044 

1  hid 

xpoi nt 

t  ra  ns late  Ta  b 1 e  po inter 

1045 

m  v  i 

d  1 0 

setup  for  Offset 

1046 

mov 

e?  a 

1047 

dad 

d 

add  offset 

1048 

shld 

x  po  i  n  t 

set  pointer 

1049 

; 

1050 

y 

Negative  Sector  Translation 

1051 

1052 

i  n 

sec 

1053 

SUI 

4 

(Continued  on  next  page) 
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1054: 

rar 

* 

divide  by  two 

1055: 

mov 

c  7  a 

1056: 

sub 

e 

" 

diff.  for  Hysteresis 

1057: 

sta 

d  i  f  f 

1058: 

mov 

e>  c 

" 

offset 

1059: 

1  hid 

y  poi nt 

J 

translation  table  pointer 

1060: 

dad 

d 

; 

offset  in  table 

1061: 

shld 

y  poi nt 

5 

set  pointer 

1062: 

ora 

a 

; 

clear  carry 

1063: 

ret 

1064: 

1065: 

Set 

fatal  error  Flas.. 

ca 1 1 e  r  p  ro  c  ess es 

1066: 

? 

the' 

error. 

1067: 

106S: 

rd*trk2 

: 

1069: 

s  t  c 

; 

carry  =  Fatal  error 

1070: 

ret 

1071: 

1072: 

1073: 

1075:  ***  "READ  SECTORS  BY  INCREMENTS  OF  TWO"  *** 

1076:  .***#*#****-*******#****4t.it***#**#******»)ti**#* 

1077: 

107S: 

1079:  Enter  with  first  sector  to  be  read  in  'A’  res. 

10S0:  ?  Returns  to  caller  on  Error  or  Last  sector. 

1081:  ;  note: 

1082:  ;  Z  flas  set  if  sood  read  else  Nz 

1083:  rd$sec: 


1084: 

call 

read 

5 

read  sector 

1085: 

i  n 

sec 

■ 

9 

current  sector 

1086: 

r  nz 

1087: 

ad  i 

o 

A. 

1088: 

out 

sec 

1089: 

emp 

c 

$ 

last  sec? 

1090: 

r  z 

9 

y  es. . . 

1091 : 

Jmp 

rd$sec 

1092: 

1093:  ##*#######*#*###*#####**#:**#*•*####*#####***##*:♦£.*•#***#**# 
1094:  **+  “THE  FOLLOWING  ARE  HARDWARE  DEPENDENT  ROUTINES"  *#* 
1095:  #*#######**###*#*#*♦*#####*##***#*###♦♦#*#*♦♦#**#*#*#**# 
1096:  ; 

1097:  ; 

1 098 :  #*+#***#*#####+**•***** 

1099:  ***  "DRIVE  SELECT"  *** 

1100:  *##***•**•#***##*#***#** 

1101:  ; 

1102:  ;  The  drive  select  routine  must  be  expanded 

1103:  ;  for  selected  systems. 

1104: 

1105:  select: 

1106: 


1107: 

i  f 

Dy  sa  n 

1108: 

mvi 

a.  21  h 

5  select  bits 

1109: 

out 

dsel 

5  sel  ect  d  rive. . . 

1110: 

end  i  f 

1111: 

1112: 

1113: 

i  f 

CCS 

JThe  upper  case  code  performs  drive 

1114: 

5  selection  on  the  CCS  2422  controller 

1115: 

?  for  si  ns  1  e  side  double  density... 

1116: 

CALL 

CLS 

j  clear  console 
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1117: 

LX  I 

H,  SELMSG 

1118: 

CALL 

TEXT  ; 

print  drive  selection  request  #/ 

1119: 

CALL 

Cl  ? 

set  response  *v 

1120: 

CPI 

’A'  5 

accept  AjB.’CjCK’  as  responses  *s 

1121: 

JZ 

SELECT 1 

1122: 

JC 

SELECT 

1123: 

CPI 

’  E  ■’ 

1124: 

JZ 

SELECT 1 

1125: 

CPI 

*C* 

1126: 

JZ 

SELECTS 

1127: 

CPI 

’D’ 

1128: 

JZ 

SELECT4 

1129: 

JMP 

SELECT  ; 

repeat  if  i nva lid  choice  +: 

1 130: 

1131: 

1132: 

SELECT4: ADI 

? 

make  low  nybble  an  8 

1 1  tf-tf : 

SELECTS: I HR 

A  ; 

make  a  4  #/■ 

1134: 

SELECT l:SU I 

’s>’  ; 

make  B  into  2  or  A  into  1  +v 

1135: 

OR  I 

OFGH  ; 

add  hish  nybble:  #s 

1136: 

; 

F  for  double  density?  B  for  si  ns  1 e 

1137: 

STA 

SELPT 

store  select  bits  for  future  use... 

1 138: 

OUT 

DSEL 

1139: 

MV  I 

A?  40H  ; 

select  side  8...  00  selects  side  1 

1140: 

1141: 

OUT 
end  i  f 

04  ; 

secondary  control  port  •tv 

1142: 

1143: 

J  m  p 

horn  e 

■  horn  e  d  r  i  v  e 

1144: 

1145:  ******************************* 
1146:  ***  "SEEK  HEAD(S)  TO  TRACK"  *** 
1 1 47 :  ♦#♦♦♦♦♦♦##♦♦♦#♦♦#♦♦♦♦♦♦♦♦♦♦♦♦♦♦ 
1148:  ; 


1149: 

■ 

Enter 

with  new 

track  location  in 

1150: 

f 

' A’  r 

es  i  s  t  e  r. 

1151: 

1152: 

t  r  a  c  k : 

1153: 

out 

data 

;  n  ew  t  ra  c  k 

1154: 

call 

cl  pend 

■  clear  FDC 

1155: 

mvi 

a > $ e e k+  ra t e  ?  seek  conirrii nd  +  step  rate 

1156: 

; 

1157: 

trackl: 

1158: 

out 

cmd 

*  issue... 

1159: 

1160: 

i  f 

Dy  sa  n 

1161: 

call 

d  el  ay 

•  delay  for  FDC 

1162: 

e  nd  i  f 

1163: 

1164: 

i  f 

CCS 

; This  controller  seems  to  need  more 

1165: 

.:  delay  -  I  can’t  explain  why...  LA 

1 166: 

call 

d  elayB 

•  delay  for  FDC 

1167: 

end  i  f 

1168: 

1169:  ; 

1170:  track2: 


1171: 

i  n 

stat 

: 

busy  ? 

1172: 

r  r  c 

; 

test 

1173: 

J  c 

track2 

J 

still  busy... 

1174: 

mvi 

a? sdelay 

set  seek  delay  bit 

1175: 

sta 

d  f  las 

1176: 

i  n 

trk 

: 

set  current  track 

1177: 

sta 

ctrk 

1178: 

ret 

1179: 


( Continued  on  next  page) 
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1186 

1181 

1182 

1183 

1184 

1185 

1186 

1187 

1188 

1 1 89 

1 1 90 

1191 

1192 

1193 

1 1 94 

1195 

1196 

1197 

1 1 98 

1199 

1200 
1201 
1202 
1203: 
1204: 
1205 
1286 

1207 

1208 

1209 

1210 
1211: 
1212 

1213 

1214 

1215 

1216 

1217 

1218 

1219 

1220 
1221 
1222 


i  f 

DELAYB :  PUSH 
LX  I 


CCS 

E:  ;  extra  delay  for  CCS  controller... 

B.2000H 


DELAYC  :  DCX  B 

MOV  Aj  C 

ORA  B 

JNZ  DELAYC 

POP  B 

RET 
e  nd  i  f 


#**###*#*###****#**#**##*#########***#* 
***  "RESTORE  HEAD 03)  TO  TRACK  ZERO"  *** 


home: 


call 
mo  i 
J  m  p 


c  1  p  e  nd 

a?  r es tor e+ rate 
t  ra ck 1 


c  1  ea  r  FDC 

;  restore  command  +  step  rate 
■  issue  command.  • . 


*#*  "READ  SECTOR  ROUTINE"  **# 
**#*##**####*#***#*#**##*♦♦** 


Enter  this  routine  with  the  sector  to 
be  read  in  the  ’A’  resister. 

This  routine  will  keep  try  ins  to  read 
the  sector  until  retry  count  eauals  zero. 


The 

1793  controller 

has  a  built-in  a  u toma  tic 

four 

retries  to  read 

ID?  so  the  value  set  in 

the 

esuate  (RETRY)  i 

s  eaual  to  C  4  *  retry  + 

read : 

out 

sec 

;  set  sector 

mvi 

e»  retry 

5  to  read 

read  1 : 

call  cl  pend  ;  clear  FDC 

call  p rs $d rna  j  p ros ram  " DMA "  co n t ro  1 1  e r 


1224 

i  f 

CCS 

1225 

LHLD 

DMA 

y 

set  pointer  to  memory  buffer 

1226 

MVI 

B;  40H 

initialize  loop  counter  for  I"0 

1227 

■ 

y 

transfers:  40  for  8"  DDj  20  for  8"  SD 

1228 

end  i  f 

1229 

1230 

Ida 

d  f  las 

j  seek  delay  flas 

1231 

ori 

rsec 

j  read  sector  command 

1232 

out 

cmd 

j  issue.. 

1233 

1234 

i  f 

Dy  san 

1235 

mvi 

a?  sdma 

•  start  transfer 

1236 

out 

dma 

1237 

1238 

e  nd  i  f 

1239 

i  f 

CCS 

1240 

BREAD:  IN 

DATA 

■ 

code  to  perform  I--'0  transfer  of 

1241 

NOV 

Mj  A 

" 

data  to  memory 

1242 

I  NX 

H 

1243 

IN 

DATA 

1244 

MOV 

Mj  A 

1245 

I  NX 

H 

1246 

IN 

DATA 

1247 

MOV 

M,  A 
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1248: 

I  NX 

H 

1249: 

IN 

DATA 

1258: 

MOV 

M ,  A 

1251 : 

I  NX 

H 

1252: 

DCR 

B 

"  decrement  loop  counter... 

1253: 

JNZ 

BREAD 

1254: 

end  l  f 

1255: 

1256: 

call 

com  p 

;  t  ra  ns  f  e  r  com  f-  1  e  t  ed 

1257: 

: 

1258: 

read 2: 

1259: 

x  ra 

•a 

'  clear  seek  delay 

1260: 

st. a 

d  f  las 

1261: 

i  n 

st. at 

•  sood  read? 

1262: 

ora 

a 

1263: 

rz 

'  y  es. .  . 

1264: 

dcr 

e 

■  count  off  retries 

1265: 

Jnz 

read  1 

J  try  as  a  in 

1266: 

i  n 

stat 

?  return  status 

1267: 

ora 

a 

1 268 : 

ret 

1269: 

1270: 

1271: 

************************************** 

1272: 

***  "WAIT  FOR 

END  OF  DMA 

TRANSFER"  *** 

1273: 

************************************** 

1274: 

1275: 

com  P  5 

1276: 

Ci  1  1 

d  e  1  ay 

j  before  each  check 

1277: 

i  n 

stat 

.:  Com  f-  1  e  t  ed  T  ra  ns  f  e  r ' 

1278: 

rrc 

1279: 

rnc 

'  YES ! 

1280: 

Jmp 

comp 

1281: 

1  ■■501- 

l  • 

1 283 :  ******************************** 
1284:  ***  "PROGRAM  DISK  CONTROLLER"  *** 
1285:  ******************************** 
1286: 

1287:  prs$dma: 

1288: 


1289: 

i  f 

Dysan 

1290: 

mv  i 

b,  15 

•  Bytes  Count 

1291: 

lxi 

h,  cmd# tbl 

?  Command  Table 

1292: 

; 

1293: 

F-r  itdmal : 

1294: 

moo 

a>  m 

.:  1  oad 

1295: 

out 

d  ma 

;  write  to  controller 

1296: 

i  nx 

h 

1297: 

d  cr 

b 

5  -1 

1298: 

J  nz 

F-rs  fdmal 

1299: 

end  i  f 

1300: 

1301: 

if 

CCS 

1 302 : 

LXI 

H, SECBUF 

store  address  of  memory  buffer  */ 

1303: 

SHLD 

DMA  : 

i n  fo inter  f o r  d i s k  con t ro ller  *v 

1 304 : 

LDA 

SELPT  ; 

set  drive  select  bits  *x 

1305: 

OUT 

DSEL  .: 

sets  autowait  for  2422  control  1  er. . .  tv 

1 306 : 

! 

to  ensure  synchronization  of  I  ■■'0  transfer 

1 307 : 

end  i  f 

1 308 : 

1309: 

ret 

1310: 

1311:  ************************************** 

1312:  ***  "COMMAND  TABLE  DMA  CONTROLLER"  *** 

1313:  ****** ****** *** * ********* ************* 

1314: 

1315:  ?  Thi  s  data  is  used  to  pros  ram  Zilos’s 

1316:  ‘  z80  DMA  controller.  (Continued  on  next  page) 
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1317 

1318 
1318 

1320 

1321 

1322 

1323 

1324 

1 325 

1326 

1327 
1328: 
1328' 

1330 

1331 

1332 
1333^ 

1334 

1335 

1336 

1337 

1338 
1338 

1340 

1341 

1342 

1343 

1344 

1345 

1346 

1347 

1348 
1348 

1350 

1351 

1 352 

1353 

1354 

1355 

1356 

1357 

1358 
1358 

1360 

1361 

1362 

1363 

1364 

1 365 

1366 

1367 

1 368 
1 368 

1370 

1371 

1372 

1373 

1374 

1375 

1376 

1 377 

1378 
1 378 

1 380 

1381 
1  382' 

1383 

1384 


cmd  1 1 1>  1  s 


i  f 

Dysan 

db 

0c3h 

?  Re-Set  DMA  Controller 

db 

8bh 

•  Clear  Block  Counter 

db 

78  h 

■  Recieve  Block 

dw 

s  e  c  b  u  f 

;  Address  To  Store  Block 

dw 

256 

;  Block  Size 

db 

1 4h 

;  Define  Port  Address 

db 

28  h 

;  Define  Port  <A>  Address 

db 

85  h 

db 

data 

",  Data  Re?  FDC 

db 

8a  h 

■  Set  DMA  Controller  Active  HIGH 

db 

Ocf  h 

db 

3 

5  Data  - >  Memory 

db 

9cf  h 

end  i  f 

######**##******#***#*#***********#* 

***  "CLEAR  PENDING  COMMANDS  FDC "  *** 

#*•+ tf*###***#*#*#***#**##***###****** 

*  Clears  the  floppy  controller  of  any 

;  pend  in?  comma  rids. 


cl  pend : 

mo i  a > clear  ‘  clear  FDC  command 

out  cmd  J  issue... 


*****#*#*#*****  ************************ 
:+:*+  "FDC  DELAY  TO  PROCESS  COMMANDS"  *** 
*************2W************ ************ 


This  delay  must  be  adjusted  for  different 
clock  speeds.  59  usee  delay  loop. 


Note: 

If  altered>  AJust  Index  Timins  Routine. 


delay: 

a 

!  4. 25 

m  v  i 

a?  fd  el  ay  ! 

!  1.  75 

delay  1 : 

dcr 

•i  ' 

11.  00 

J  nz 

delay  1 

27.  50 

nop 

3 

1.  00 

nop 

3 

1.  00 

n  of- 

1.  00 

ret 

2.  50 

******************************** 
***  "RADIAL  TRANSLATE  TABLE"  *** 
******************************** 


Cursor  Posit ion in?  tabl 
‘  alisnment  test. 

radSne? : 


db 

38 

db 

36 

db 

34 

db 

70 

db 

30 

db 

28 

db 

26 

db 

24 

db 

f  o  r 

radial 

1 

mi  1 1  i  n 

II  •! 

T 

II  II 

4 

II  II 

5 

II  II 

6 

■  I  II 

s 

9 

II  II 

II  II 

II  II 
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1385: 

db 

20 

?  10  "  " 

1386: 

db 

17 

,  n  H 

1337: 

db 

14 

S  12  " 

1388: 

db 

11 

?  13  " 

1389: 

1390: 

radfpos: 

1391: 

db 

40 

j  1  mi  11  inch 

1392: 

db 

42 

•  ^  II  II 

7 

1393: 

db 

44 

;  3  " 

1394: 

db 

46 

J  4  " 

1395: 

db 

43 

5  5" 

1396: 

db 

50 

;  6  " 

1397: 

db 

52 

a  II  II 

7  1 

1398: 

db 

54 

a  Q  II  II 

7  O 

1399: 

db 

56 

-  9  H  •• 

1400: 

db 

58 

5  10  " 

1401: 

db 

61 

.  U  „ 

1402: 

db 

64 

;  12  " 

1403: 

db 

67 

;  13  " 

1 404  : 

1 405 :  ***#+.+**#####*#+'***♦******#:**#**# 

1406:  ***  "AZIMUTH  TRANSLATE  TABLE"  *** 

1407:  ##***#+*#+*♦**•##*#**•#***#**#*##*# 

1 40S : 

1409:  azi$tab: 

1410:  db  IS  *  head  azmuith  ansle 

1411:  db  20  >  +/-  minutes 

1412:  db  22 

1413:  db  24 

1414:  db  26 

1415:  db  28 

1416:  db  30 

1417:  db  32 

1418:  db  34 

1419:  db  36 

1420:  db  38 

1421:  db  40 

1422:  db  42 

1423: 

1 424 :  a###*#***#**#**********#** 

1425:  ***  "PROGRAM  MESSAGES"  *** 

1 426 :  ***#***######*#*#*#**#**** 

1427: 

1428:  mel: 

1429: 

1430:  db  01>  AND  OFFH, 13, 5, ’ <*>================================= 

1431:  d  b  (-1)  AND  0FFH , 13,6, ’ <* >  D I AGNOST I C  COMMAND  MENU 

1432:  db  01>  AND  OFFH, 18, 7, ’<*>================================= 

1433:  db  OD  AND  0FFH, 18,8, ’<*> 

1434:  db  O 1)  AND  OFFH,  13, 9?  *  ■(#>  R  =  Radial  H  =  Hysteresis 

1435:  db  01>  AND  0FFH, 13, 10, ’<*> 

1436:  db  On  AND  OFFH, 18, 1 1 , ’<*>  A  =  Azimuth  I  =  Index  Timi 

1437:  d  b  <-l>  AND  0FFH , 18,12,’  < * > 

1438:  db  01)  AND  0FFH, 13, 13, ’ <*>  C  =  Centering  S  =  Spindle  Sp 

1439:  d b  0 1>  AND  0FFH , 1 8 , 1 4 , ’ <  *> 

1440:  db  0 1>  AND  OFFH, IS, 15, ’<*>  D  =  Drive  Sel  E  =  Exit  Pro?  r 

1441:  db  OD  AND  8FFH,  18, 16,  ’ <*> 

1442:  d  b  <  - 1  >  AND  OFFH ,  1 8 , 1 7,  ’  <  *  X  *  X  #<  *  ><  *  X  *  >< * ><  *  ><  *  X  *  ><  *  ><  *  >< 

1443:  d  b  01>  AND  OFFH,  18,  19,  ’  SELECTION? _ ’ ,  bs,0 

1444: 


1445: 

me2* 

db 

’FATAL  READ  ERROR 

’  ,0 

1446: 

me3s 

db 

’RE-CLAMP  DISKETTE 

a  a  a  a  '  7  tS  ?  0 

1447: 

me4: 

db 

’CENTERING  OK  .... 

S  bs,0 

1448: 

me5s 

db 

’  Minutes 

?  ,  0 

1449: 

1450: 

rn&7s 

db 

01>  AND  OFFH,  25,  2, 

»  y  >============  ====  ===:=  =  =:==  ==<•>? 

1451:  db  (-1)  AND  OFFH,  25,3, ’O  TRACK  SELECTION  O’ 

1452:  db  00  AND  0FFH, 25, 4,  ’<>==========================<  >’ 

(Continued  on  page  78) 
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Diagnostic  Diskette  Listing  (Listing  continued,  text  begins  on  page  40) 


1453: 

db 

C-l)  AND  ©FFH, 25, 5, ’ O 

1454: 

db 

C-l)  AND  ©FFH, 25, 6, ’<> 

A  =  C0) 

D  =  C  4 1 ) 

1455: 

db 

C-l)  AND  0FFH, 25,7, ’ O 

1456: 

db 

C-l)  AND  0FFH, 25,  S,’<> 

B  =  C3) 

E  =  C70) 

1457: 

db 

C-l)  AND  0FFH, 25,  9, ’<> 

1458: 

db 

C-l)  AND  0FFH,25, 10, ’<> 

C  =  C38) 

F  =  C73) 

C-l)  AND  0FFH,25,11,'O  O' 

C-l)  AND  0FFH, 25, 12,  ’  < >==========================< >’ 

C— 1)  AND  0FFH, 25, 13, ' O  <ESC>  Cancels  Test  O' 

C-l)  AND  0FFH,25,  14,  ’<>======*===================<>' 

C-l )  AND  0FFH, 25, 16, ’ TRACK?  . . .  ’ , bs, 0 

C-l)  AND  0FFH, 24, 5, ’ -  RADIAL  ALIGNMENT  CHECK  - ’ 

<-l>  AND  0FFH, 10,9, 'Away',  C-l)  AND  0FFH, 36,9, ’ Spi nd  1  e  ’ , C 
C-l)  AND  0FFH, 10, 10, ' 13  12  11  10  987654321' 

'-1  23456789  10  11  12  13', 0 

C-l)  AND  0FFH, 25, 2, '<>==========================<>’ 

C-l)  AND  0FFH, 25, 3, ’ < >  TRACK  SELECTION  O' 

C-l)  AND  0FFH, 25, 4, ’<>==========================<>’ 

C-l)  AND  0FFH,  25,  5, '  O  O’ 

C-l)  AND  0FFH, 25, 6, ’ <>  A  =  C35)  B  =  C44)  O' 

C-l)  AND  0FFH, 25,  7,  ’ O  O' 

C-l  )  AND  ©FFH, 25, 8,  ' < >  C  =  C47)  O' 

C-l)  AND  0FFH, 25,  9,  ’ O  O’ 

C-l )  AND  0FFH,  25, 10,  ’  <  >=========================<  >’ 

C-l)  AND  0FFH, 25, 1 1 , ’ O  <ESC>  Cancels  Test  O' 

C-l)  AND  0FFH,25, 12, '<>==========================<>' 

C-l )  AND  0FFH, 25, 14, ’ TRACK?  . .  . ’ , bs, 0 

C-l)  AND  0FFH, 23, 5, ’ -  DISKETTE  CENTERING  CHECK  - ’,0 

C-l)  AND  @FFH,23, 14, 'Press  < SPACE  BAR)  For  New  Track’,0 

C-l)  AND  0FFH, 24, 5, ' -  AZIMUTH  ALIGNMENT  CHECK  - ’ 

C-l)  AND  @FFH,2S, 14, ’<ESC>  Will  Cancel  AZIMUTH  Check' ,0 

C-l)  AND  0FFH, 25, 2, ’ < >==========================<>’ 

C-l)  AND  0FFH, 25, 3, '<>  TRACK  SELECTION  O’ 

C-l)  AND  0FFH, 25, 4, ’ <  >==========================< >’ 

C-l)  AND  0FFH, 25,5,  ’ <>  O’ 

C-l)  AND  0FFH,25,6»  ’<>  A  =  (0)  B  =  C76)  O’ 

C-l)  AND  0FFH,  25, 7,  ’  <  >  O' 

C-l)  AND  0FFH, 25, 8, ’ < >==========================< >’ 

C-l)  AND  0FFH, 25, 9, ’ < >  <ESC>  Cancels  Test  O’ 

C-l)  AND  0FFH, 25, 10, ’<>==========================<>’ 

C-l )  AND  0FFH, 25,12,’ TRACK?  . . . ’ , bs, 0 


m  e  1 5 : 


mel9: 


C-l)  AND  0FFH, 15,8, ’#################################### 
C-l)  AND  0FFH, 15, 12, ’#################################### 

C-l)  AND  0FFH, 27, 5, ’ -  SPINDLE  SPEED  CHECK  - ’ 

C-l)  AND  0FFH,25, 14, ’<ESC>  Will  Cancel  RPM  Check’, 0 


me20:  db 

me2l:  db 

BLANKS:  DB 
DB 

SELMSG:  DB 
DB 


’  Milliseconds’,© 
’  RF'M’,0 


C-l)  AND  0FFH, 15, 12, ’WHICH  DRIVE  HAS  THE  DDD  -  A,B,C,D  ? 
C-l)  AND  0FFH, 25, 14, ’SELECTION  ?  _ ’,0 


* * * *  *  *  *  *  *  *  * * *  ********  *  *  *  * 
***  "POSITION  CURSOR"  *** 

*****  .-f  :f  :f'  :f  :f‘  if  :f  *  :f  :f  .f  :f  f  .f  :f  :f  * 


set$cur  db 
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column  ds 
row  ds 
db 


set  column 
set  row 
termi ns  tor 


*  :f + + *:f :f  *  :f  :f  :f  *  .f  :*  :f 

**+  "PROGRAM  VARIABLE  STORAGE"  *** 
*******#*+********+*****.f:f****+***+ 


t  ern  p 
di  ft 
ctrk 
savtrk 
d  f  las 
poi  nt 
xpoi nt 
y  po i n  t 
xof  f 
yo  f  f 
bais 
hy  err 
SELPT 


j  temp  s to rase 
;  1st  -  2nd  read 
;  current  track 
;  temp  s to rase  Hysteresis  test 
j  seek  delay  flas 
;  table  pointer 
j  table  pointer  positive 
;  table  pointer  nesative 
’  positive  offset 
;  negative  offset 

;  bais  from  test  track  (Hysteresis) 
;  hysteresis  error  on  first  read  ins 
STORES  BYTE  FOR  DISC  CONTROL  PORT 


Storase  area  for  16/24  bit  divide  routine 


1547 

msb 

ds 

i 

154S 

rnsbl 

ds 

1549 

ms  b2 

ds 

1550 

1551 

i  n  b  u  f : 

db 

3 

; "max"  byte  for  BDOS  10 

1552 

i  ncnt 

ds 

i 

;"cnt"  buffer  for  BDOS 

1553 

buffer 

ds 

4 

;  console  input  buffer 

1554 

s  e  c  b  u  f 

ds 

256 

•  sector  buffer 

1555 

1556 

ds 

100 

5  stack  space 

1557 

tack 

e-au 

$ 

5  top  down. . . 

End  Listing 
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Building  a  Programmable 
Frequency  Synthesizer 


The  Master  Controller  Board  (MCB), 
a  single-board  computer  available 
from  Space-Time  Productions,  Chi¬ 
cago,  Illinois,  has  an  8253  counter/timer 
on  it  that  is  used  for  a  baud  rate  generator. 
Since  it  has  two  spare  counter  time  chan¬ 
nels,  I  decided  to  use  them  to  construct  a 
crystal-controlled  programmable  frequen¬ 
cy  synthesizer. 

Phase -Locked  Loop  (PLL)  Theory 

A  phase-locked  loop  is  a  very  useful 
combination  analog  and  digital  device.  It 
enables  a  digital  frequency  divider  to  mul¬ 
tiply  frequencies  exactly.  It  performs  this 
trick  by  controlling  the  frequency  and 
phase  of  a  voltage -controlled  oscillator 
(VCO)  in  such  a  wav  that  the  VCO  is 
locked  into  the  frequency  and  phase  of  a 
reference  oscillator.  (See  Figure  1,  below.) 


by  Michael  L.  Simon 

Michael  L.  Simon,  Space-Time  Produc¬ 
tions,  2053  N.  Sheffield,  Chicago,  Illinois 
60614. 

Copyright  ©  1983  Michael  L.  Simon.  All 
rights  reserved. 

Permission  is  granted  for  non-commercial 
use  only.  Any  commercial  use  without 
permission  from  the  author  is  prohibited. 


An  example  will  help  to  explain  the 
operation.  A  reference  frequency  of  1000 
Hz  is  available; it  is  used  as  one  input  to  a 
phase  comparator.  The  other  input  comes 
from  the  output  of  the  VCO  through  a 
programmable  divider,  which  is  set  to 
divide  by  four.  For  the  loop  to  be  locked, 
the  output  of  the  programmable  divider 
must  be  1000  Hz.  If  the  frequency  is  low, 
the  phase  comparator  will  generate  longer 
pulses  which,  when  averaged  by  the  low 
pass  filter,  will  create  a  higher  voltage  at 
the  input  of  the  VCO.  This  will  cause  the 
output  of  the  VCO  to  increase  in  frequen¬ 
cy,  maintaining  an  output  of  4000  Hz. 

Similarly,  if  the  output  of  the  VCO  is 
above  4000  Hz,  the  phase  comparator 
will  generate  shorter  pulses.  This  will 
reduce  the  frequency,  again  restoring  the 
original  4000  Hz.  Thus  a  phase-locked 
loop  and  a  divide-by-four  circuit  are  able 
to  multiply  an  input  frequency  by  four. 
If  the  input  to  the  reference  of  the  loop 
has  high  stability,  the  output  of  the  loop 
will  also  tend  to  have  high  stability. 

Figure  2  ( page  8 1 )  shows  the  circuit 
diagram  of  a  phase-locked  loop. 

The  4046  CMOS  Phase -Locked 
Loop  Chip 

The  4046  is  a  CMOS  phase-locked 
loop  which  is  fairly  inexpensive  and  oper¬ 


ates  over  a  wide  frequency  range  (from 
less  than  1  Hz  to  over  1  million  Hz).  The 
4046  has  a  phase  detector  that  is  edge 
sensitive.  This  is  useful  when  the  signals 
to  be  synchronized  are  not  perfect  square 
waves.  The  chip  has  a  second  phase  detec¬ 
tor  that  can  be  used  to  tell  if  the  loop  is 
out  of  lock.  Because  the  4046  is  a  CMOS 
device  with  high  input  impedance,  loop 
filters  with  high  value  resistors  and  low 
value  capacitors  are  possible.  This  makes 
possible  low-frequency  loop  filters  built 
from  small,  inexpensive  capacitors. 


The  Single -Board  Computer 

The  MCB  is  a  Z80-based,  single-board 
computer  with  many  useful  features. 
Among  these  features  are  72  parallel 
I/O  lines,  two  serial  I/O  ports,  and  two 
counter/timer  chips  with  a  total  of  eight 
counter/timers.  Also  available  for  the 
board  is  a  version  of  the  TDL  monitor, 
modified  to  allow  control  of  the  program¬ 
mable  dividers  of  the  8253.  This  program 
makes  frequency  synthesizer  experiments 
a  snap  since  it  has  commands  that  directly 
control  the  dividers  in  the  8253  counter/ 
timer  chip. 

One  channel  of  the  8253  is  used  for 
the  on-board  baud  rate  generator.  Each 
channel  of  the  baud  rate  generator  is  set 
up  for  a  different  baud  rate;  three  rates 


Voltage  Controlled 

Low  Pass  Filter  Oscillator 


Frequency 

Reference 


Fref 


Figure  1. 

Phase-locked  loop  (PLL)  example. 
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Figure  2.  ©m.  Simon 

Phase-Locked  Loop.  12:18Z  13  Sept.  81  /  12:14Z  18  Nov.  81 


(110,  300,  and  4800)  are  available.  Since 
I  use  300  baud  to  talk  to  the  MCB,  which 
uses  channel  1  of  the  8253,  channels  0 
and  2  are  available  for  experiments.  The 
8253  is  set  up  by  the  monitor  program  to 
act  as  a  programmable  divide-by-N  circuit 
and  to  produce  a  square  wave.  If  N  is  an 
even  number,  the  output  will  be  a  square 
wave.  If  N  is  an  odd  number,  the  output 
will  be  approximately  a  square  wave  with 
one  half  of  the  cycle  longer  than  the 
other  half;  refer  to  Figure  3  (page  82) 
and  Listing  One  (page  88). 

The  gate  of  each  channel  used  must 
be  pulled  high  for  the  8253  to  perform 
the  divide  function.  A  2  MHz  buffered, 
crystal-controlled  reference  signal  is  avail¬ 
able  from  the  CPU’s  clock  generator.  This 
signal  is  required  by  the  baud  rate  genera¬ 
tor  and  is  brought  to  pin  20  of  header  J-4 
from  the  pads  near  the  crystal  by  a  jumper 
wire  soldered  to  the  underside  of  the 
board.  From  this  pin  I  used  reuseable 
jumper  wires  on  the  header  pins  to  bring 
the  2  MHz  signal  to  the  inputs  of  counters 
0,  1,  and  2.  These  jumper  wires  are  about 
the  handiest  I  have  ever  used  on  .025 
square  pins.  They  make  wrapped  wire 
methods  seem  very  clumsy,  especially 
when  doing  experiments,  since  the  sock¬ 
eted  jumpers  are  easy  to  move  and  reuse. 

After  hooking  up  the  PLL  according 
to  diagram  2,  I  expected  an  output  fre¬ 
quency  of  about  45,775  Hz  —  I  say 
“about”  because  the  output  frequency 
depends  on  the  exact  frequency  of  the 
CPU  time  base  generator  and  the  divide 
ratios  chosen  for  the  baud  rate  generators. 
My  oscillator  was  slightly  low,  so  I  got  a 
different  value. 

I  prepared  a  chart  of  divide  ratios 
versus  hexadecimal  numbers.  The  baud 
rate  generators  could  be  programmed  to 
recognize  decimal  values.  However,  by 
using  hexadecimal  numbers,  over  six 
times  the  range  of  divisors  is  possible. 

My  first  experiment  was  to  get  the 
system  to  go  out  of  lock  on  the  low  end. 
The  frequency  at  which  this  happens  de¬ 
pends  on  the  components  used  in  the 
loop  filter.  With  the  components  chosen, 
the  loop  goes  out  of  lock  at  a  reference 
frequency  of  about  200  Hz  into  the  phase 
comparator.  The  exact  frequency  will 
vary  with  the  rate  at  which  the  PLL  has 
to  change  between  new  inputs.  The  loop 
goes  out  of  lock  on  a  jump  from  divide- 
by-1000  hex  to  divide-by-2000  hex  on 
the  channel  2  counter.  However,  if  you 
can  inch  up  to  1F00  and  keep  the  loop  in 
lock,  it  is  possible  to  jump  from  there  to 
2000  hex  and  still  keep  the  loop  in  lock. 

The  same  method  is  used  for  getting 
the  loop  back  in  lock  from  an  out-of-lock 
condition.  To  get  the  loop  to  respond  to 
lower  frequencies  and  still  stay  in  lock, 
try  increasing  R5  and  C5.  (Check  out 
Design  of  Phase  Locked  Loop  Circuits 


With  Experiments  by  Howard  M.  Berlin, 
Howard  W.  Sams  Inc.,  for  methods  of 
determining  the  best  values  for  the  loop 
filter.) 

On  the  high  end  it  is  possible  to  keep 
the  loop  in  lock  until  well  past  1  MHz. 
However,  I  have  had  some  PLL’s  lock  up 
at  the  high  frequencies.  This  is  probably 
due  to  the  speed  limitation  of  the  chips  I 
used.  By  removing  power  and  beginning 
again,  everything  was  returned  to  normal. 

Solid  State  Scientific  of  Montgomery, 
Alabama,  makes  a  version  of  the  4046 
with  a  VCO  guaranteed  to  oscillate  up  to 
5  MHz.  The  part  is  called  a  4446.  By 
reducing  capacitor  C2  to  50  pf,  I  got 
mine  to  stay  in  lock  past  2.5  MHz.  For 
those  who  want  to  go  past  2.5  MHz,  I 
recommend  using  about  20  pf  at  C2.  You 
must  also  use  a  divider  capable  of  higher 
frequency  input  than  the  8253.  Fortu¬ 
nately,  the  Master  Controller  Board  has  a 
socket  for  the  AMD  9513  counter/timer, 
which  is  guaranteed  up  to  7  MHz. 

It  is  possible  to  generate  almost  any 
frequency  with  the  right  choice  of  dividers. 
For  example,  I  wanted  to  tune  up  my  AM 
radio.  To  do  this  I  needed  to  tune  up  the 
intermediate  stages  first.  This  requires  a 
frequency  of  455,000  Hz.  With  the  crystal 
in  my  board,  loading  counter  0  with  3A4 
hex  and  counter  2  with  1000  hex  gave  me 
a  readout  on  my  frequency  counter  of 
454,995.0  Hz.  Not  bad,  but  I  wanted  to 
get  closer. 

The  first  step  was  to  determine  the 
frequency  of  the  clock  on  the  MCB. 
Checked  with  my  trusty  calculator,  3A4 
converted  to  decimal  is  equal  to  932; 
1000H  is  4096.  Dividing  454,995  Hz 
by  932  found  the  reference  frequency. 
Multiplied  by  4096,  the  result  was  the 
crystal -controlled  input  clock  frequency. 
My  result  was  1,999,634.6  Hz. 

The  dilemma  now  was  to  determine 
which  divider  ratios  would  yield  the 
correct  output  frequency.  There  is  a 
formula  for  doing  this.  Unfortunately,  I 
had  long  since  forgotten  it,  so  I  inventea 
a  trial -and -error  method  to  determine 
the  correct  divisors.  Since  computers  are 
much  faster  at  trial  and  error  than  humans, 
I  wrote  a  BASIC  program  (see  Listing 
Two,  page  91)  to  handle  it.  If  I  had 
known  the  right  algorithm,  there  would 
have  been  quicker  results,  but  the  pro¬ 
gram  does  the  job. 

The  main  idea  is  that  the  phase-locked 
loop  may  be  used  to  generate  any  desired 
frequency  to  any  degree  of  accuracy  by 
choosing  the  right  values  for  the  control¬ 
ling  dividers.  By  using  this  program,  I 
came  up  with  values  of  808  for  divider 
#0  and  355  1  for  divider  #2.  This  gives  an 
accuracy  of  0.13  ppm.  I  converted  808 
and  3551  to  hexadecimal  (328h  and 
ODDFh)  and  entered  the  values  in  the 
8253.  455,000.0  Hz  was  the  result ! 

With  suitable  dividers  following  the 


loop  output,  audio  tones  can  be  generated. 
These  could  be  used  to  fine  tune  your 
favorite  string  instrument  (see  Figure  4, 
page  82).  The  4040  circuit  gives  output 
ranging  from  the  lowest  to  the  highest 
octave,  evenly  spaced  at  octave  intervals. 
The  even-tempered  scale  used  in  most 
musical  instruments  uses  twelve  notes  per 
octave  interval.  Each  note  is  higher  in 
frequency  than  the  preceding  note  by  a 
factor  of  1.0594631.  Table  I  (below) 
gives  a  series  of  frequencies  that  facilitates 
tuning  all  the  notes  in  any  octave.  The 
beauty  of  this  set-up  is  that  with  the 
proper  choice  of  dividers,  any  scale  may 
be  reproduced,  regardless  of  the  number 
of  notes  or  the  size  of  the  interval. 

The  Phase-Locked  Loop  board  is  a- 
vailable  as  a  kit  for  $28.75  postpaid  from 
Space-Time  Productions,  2053  N.  Shef¬ 
field,  Chicago,  Illinois  60614;  (312) 
327-0391.  The  Master  Controller  Board 
is  available  bare  for  $54.90  with  postage. 
The  customized  TDL  Monitor  is  available 
for  $69.90.  A  partially  populated  MCB, 
assembled  and  tested,  running  Tiny  Con¬ 
troller  Basic,  is  $304.90  with  postage. 

BIJ 

( Listing  begins  on  page  88 ) 
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Note 

Rat  i  o 

Input  to  4040  Divider 

A- 440 

A 

1 . 0000000 

450560.00  Hz 

440. 00000  Hz 

A# 

1 . 0594631 

477351.69  Hz 

466. 16375  Hz 

B 

1 . 1224620 

505736.47  Hz 

493.88327  Hz 

C 

1 . 1892071 

535809.15  Hz 

523.25112  Hz 

C# 

1 . 2599210 

567670.00  Hz 

554 . 36523  Hz 

D 

1 . 3348398 

601425.42  Hz 

587.32951  Hz 

D# 

1.4142135 

637188. 03  Hz 

622.25393  Hz 

E 

1 . 4983071 

675077.20  Hz 

659.25507  Hz 

F 

1 . 5874010 

715219.44  Hz 

698.45648  Hz 

F# 

1.6817928 

757748.56  Hz 

739.98882  Hz 

G 

I.7817974 

802806.63  Hr 

783.99084  Hr 

G# 

1 . 8877486 

850544.00  Hz 

830.60937  Hz 

A 

2. 0000000 

901120.00  Hz 

800.00000  Hz 

Table  1 

Twelve  Tone  Scale  Frequencies 

84 
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Frequency  Synthesizer  (Text  begins  on  page  80) 
Listing  One 


;  11 : 58z  22  MARCH  83  CT  FOR  PLL  ART 
CDL's  ZSO  Macro  Assembler  C12012-0312 

Modified  for  MASTER  CONTROLLER  BOARD  21  MARCH  83  M. Simon 

;  EQUATES  FOR  THE  8253  TIMER  CHANNELS 


006C 

CTR0 

==  6Ch 

; 8253  CHAN  0 

006D 

CTR1 

==  CTR0+1 

006E 

CTR2 

==  CTR0+2 

006F 

CTRTC 

=  =  CTRO+3  ;  8253  CONTROL 

;  CHANNEL 

;THE  " 

BAUD"  PROGRAM  GETS  TWO  PARAMETERS  OFF  THE 

;  STACK.  THE  F 

IRST  OFF  THE  STACK  IS  A  TWO  BYTE 

;  HEX 

NUMBER  THAT  IS  THE  DIVIDER  THAT  IS  TO  BE 

;  USED 

BY  THE 

COUNTER.  THE  SECOND  NUMBER  IS  USE 

;  TO  DETERMINE 

THE  COUNTER  TO  BE  USED. 

;  D 1 V 1 DERS  CAN 

BE  FROM  2  TO  OFFFFh,  COUNTERS 

;  ARE 

/ 

0,1,  & 

2 

017A 

CD  055E 

BAUD: 

CALL 

EXPR  ; GET  2  PARAMS 

;  &  PUT  THEM  ON 

;  THE  STACK 

017D 

Dl 

POP 

D  ; BAUD  RATE 

017E 

El 

POP 

H  ; COUNTER  # 

017F 

7D 

BR!  : 

MOV 

A, L  ; TEST  FOR  CTR  # 

0180 

B  7 

ORA 

A 

0181 

2809 

JRZ 

OUTCO 

0185 

3D 

DCR 

A 

0184 

2811 

JRZ 

OUTC1 

0186 

3D 

DCR 

A 

0187 

2819 

JRZ 

OUTC2 

0189 

C 2  057F 

JNZ 

ERROR 

018C 

3E36 

OUTCO : 

MV  1 

A,  00110110B 

018  E 

D36F 

OUT 

CTRTC 

0190 

7B 

MOV 

A,  E 

0191 

D  3  6  C 

OUT 

CTRO 

0193 

7  A 

MOV 

A,  D 

0194 

D36C 

OUT 

CTRO 

0196 

C  9 

RET 

0197 

3E76 

OUTC1: 

MV  1 

A, 011101 10B 

0199 

D36F 

OUT 

CTRTC 

019B 

7  B 

MOV 

A,  E 

019C 

D3  5D 

OUT 

CTR  1 

01 9  E 

7A 

MOV 

A,D 

0 1 9  F 

D36D 

OUT 

CTR  1 

01A1 

C  9 

RET 

88 
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01A2 

3EB6 

0UTC2 :  MV  1 

A, 10110110B 

01A4 

D36F 

OUT 

CTRTC 

0 1A6 

7B 

MOV 

A,  E 

01A7 

D  3  6  E 

OUT 

CTR2 

01A9 

7A 

MOV 

A,  D 

01AA 

D36E 

OUT 

CTR2 

0 1AC 

C  9 

RET 

; TH I S  PROGRAM  DOES  THE  POWER  ON  INITIALIZATION  OF 
;  THE  8253  COUNTER  TIMERS.  THIS  PROGRAM  IS  CALLED 
;  BY  THE  MAIN  INITIALIZE  PROGRAM.  THE  THREE 
;  COUNTER  TIMERS  ARE  SET  UP  FOR  BAUD  RATE 


;  GENERATORS.  CHAN. 

#0  =  4800  BAUD 

;  CHAN.  #1  =  300 

BAUD  CHAN.  #2  = 

110  BAUD 

.  01C8 

CT53IN: 

"  01C8 

2E00 

MV  1 

L,0 

;  1  NIT  CTR  0 

0 1CA 

11  001A 

LX  1 

D,26. 

;  FOR  2Mhz  CLOCK, 

;  4800  BAUD 

01CD 

CD  017F 

CALL 

BRI 

01D0 

2E01 

MV  1 

L,1 

;  CTR  1 

01D2 

11  01A1 

LX  1 

D,  4 17 . 

;  300  BAUD 

01D5 

CD  0 1 7 F 

CALL 

BRI 

01D8 

2E02 

MV  1 

L  /  2 

;  CTR  2 

01DA 

11  0470 

LX  1 

0,1136. 

;  110  BAUD 

0 1DD 

CD  017F 

CALL 

BRI 

01E0 

C9  . 

RET 

End  Listing  One 

Listing  Two 

PROGRAM  #1 

10  X=3 

;;  T I MER 

2  DIVIDE  NUMBER 

20  Y®3 

; TIMER 

0  DIVIDE  NUMBER 

30  PRINT 

"INPUT  CLOCK  FREQUENCY": INPUT  C 

40  PRINT 

"  OUTPUT 

FREQUENCY" : INPUT  0 

SO  I — G/C  5  RATIO  OF  OUTPUT  TO  CLOCK 

60  PRINT  "INPUT  ACCURACY  IN  PPM" s INPUT  A 


70  A=A/1E6 

80  Z“  <I--(Y/X)>/I 

90  IF  ABB  ( Z ) < A  THEN  GOTO  1000 

100  IF  Z>0  THEN  600 

110  IF  Z<0  THEN  500 

120  GOTO  1000 

500  X—X  +  l :  GOTO  80 

600  Y»“Y+1  :  GOTO  80 

1000  PRINT . TIMER  #2  DIVIDER"  X, "TIMER  #0  D I V I DER " Y 

1010  PR I NT "ACTUAL  ACCURACY"  1 


1020  GOTO  10 


End  Listing  Two 
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CP/M  EXCHANGE 


by  Robert  Blum 


The  column’s  a  little  short  this  month 
due  to  an  accelerated  deadline  caused  by 
CP/M  ’83.  The  interface  series  that  I  prom¬ 
ised  would  start  this  month  will  be  held  off 
until  next  month.  I  apologize  for  the  delay 
but  I  think  you  will  enjoy  it  once  it  starts. 

User  Areas  —  Bah,  Humbug 

Several  months  ago,  I  cried  on  your 
shoulder  about  how  old  and  decrepit  my 
system  had  become.  Well,  since  then,  new 
disk  drives  have  been  installed,  a  new 
motherboard  is  now  keeping  a  handle  on 
the  bus  signals,  and  a  15MB  hard  disk 
happily  gobbles  up  all  the  data  I  can  feed 
it.  Unfortunately,  I  should  never  have 
installed  the  hard  disk  because  it  pointed 
out  to  me  one  black  hole  that  exists  in 
CP/M:  there  is  no  easy  way  to  partition 
logically  related  groups  of  data  files. 

Let  me  explain  a  little  further.  Right 
from  the  beginning  I  delegated  my  floppy 
disk  drives  to  specific  tasks.  Drive  A:  is 
called  the  runtime  drive.  It  contains  only 
executable  (.COM)  files  and  any  tempor¬ 
ary  work  files  that  may  be  needed  by  the 
application  programs.  Drives  B:  and  be¬ 
yond  are  used  for  data  files.  I  adopted 
this  arrangement  because  it  eliminates 
any  confusion  when  switching  from  one 
application  system  to  another.  When  I 
want  to  run  word  processing,  the  WP  run¬ 
time  disk  goes  into  drive  A:,  and  one  of 
various  WP  data  disks  is  mounted  in  a 
drive  designated  for  data  files.  Very  sim¬ 
ple,  very  clean,  and  easy  to  manage. 

Now  comes  the  puzzle:  how  to  allo¬ 
cate  the  hard  disk  so  it  is  able  to  fit  into 
my  established  scheme.  My  first  attempt 
was  to  split  the  15MB  into  two  logical 
CP/M  disks.  The  first  one,  drive  C:,  was 
8MB  in  size  with  all  remaining  space  given 
to  drive  D: .  Merrily  I  copied  disk  after 
disk  of  data  onto  the  Winchester.  It’s 
hard  to  describe  my  feeling  of  excitement 
as  the  data  was  gobbled  up  by  an  insatiable 
appetite.  However,  I  became  concerned 
after  I  ran  my  first  directory  listing.  Dis¬ 
played  was  such  a  hodge-podge  of  files 
that  I  knew  something  had  to  be  changed. 

I  shuddered  at  my  first  thought  — 
mapping  a  number  of  logical  floppies 
onto  the  hard  disk.  Fortunately,  it  was 
only  a  fleeting  thought.  Even  as  I  write 
this  I  can  hear  somebody  scraping  their 
fingernails  across  a  blackboard. 

User  numbers  would  partition  the 
files  the  way  I  wanted,  but  at  the  expense 
of  duplicating  a  number  of  programs  in 
each  of  the  user  areas.  The  overhead  of 
multiple  copies  of  the  same  program  is 


92 

/?4 


mandated  by  CP/M  2.2’s  inability  to 
automatically  switch  user  areas  when 
searching  for  a  file.  For  example,  if  you 
are  currently  in  user  area  three,  any  file 
that  is  opened  must  also  be  in  the  same 
user  area.  This  includes  program  overlays. 
One  solution  to  the  problem  would  be  to 
use  a  CCP  replacement  such  as  ZCPR,  but 
this  would  only  provide  a  partial  solution 
because  an  expanded  search  would  only 
be  available  when  ZCPR  was  resident. 
Once  the  executable  program  is  loaded  it 
has  no  way  of  knowing  what  user  area  it 
came  from  and  hence  no  way  of  finding 
its  overlays.  Unfortunately,  when  Digital 
Research  designed  user  areas,  they  failed 
to  provide  a  means  by  which  a  file’s  FCB 
could  communicate  to  the  BDOS  which 
user  area  it  is  in. 

I  don’t  mean  to  place  all  the  blame 
on  DR  for  this  inadequacy.  They  provided 
a  BDOS  function  that  will  switch  the  user 
area  for  any  application  program  that  is 
smart  enough  to  use  it.  Unfortunately, 
none  of  the  application  developers  decided 
to  use  it.  Micro  Pro  took  one  step  in  the 
right  direction  by  modifying  WordStar  to 
look  at  drive  A:  for  its  overlay  files  if 
they  are  not  found  on  the  currently 
logged -in  floppy.  This  is  better  than 
nothing,  but  if  the  user  area  is  not  taken 
into  account,  it  is  of  little  use.  Of  course, 
at  the  time  that  CP/M  2.2  became  availa¬ 
ble,  disk  capacities  were  relatively  low 
and  disks  were  typically  swapped  for  each 
application.  Today,  however,  hard  disks 
are  common  and  there  is  no  excuse  for 
having  to  allocate  15MB  of  space  into 
logical  floppies.  As  much  as  I  hate  to 
admit  it,  the  standard  version  of  CP/M 
2.2  simply  isn’t  suited  to  the  hard  disk 
environment. 

It  wouldn’t  seem  too  difficult  to  trap 
all  the  disk  I/O  BDOS  calls  and  swap  the 
user  area  for  FCBs  that  contain  a  file  ex¬ 
tension  of  .COM  or  overlays  that  reside  in 
the  same  user  area.  One  problem  with  this 
occurs  when  an  overlay  file  doesn’t  use 
.OVR  for  its  extension.  However,  a  little  ex¬ 
tra  code  could  provide  the  desired  results. 

Converting  to  CP/M  Plus  would  solve 
my  problem.  As  a  standard  feature,  it  will 
search  user  area  zero  for  any  file  that  is  not 
found  in  the  current  user  area,  although 
there  are  some  restrictions.  The  target  file 
must  be  marked  with  the  $SYS  attribute, 
and  it  cannot  be  written  to.  This  arrange¬ 
ment  works  well  for  executable  programs, 
which  is  what  I  am  complaining  about, 
but  for  my  money  they  don’t  get  the 
prize.  In  designing  CP/M  Plus,  DR  decided 


to  add  some  very  useful  features.  A  file 
can  be  password-protected,  and  time  and 
date  stamping  is  available  if  your  system 
supports  a  clock  of  some  sort.  To  store 
this  extra  information,  extended  directory 
entries  are  recorded  along  with  the  regular 
directory  entries. 

Unfortunately,  to  cross-access  user 
areas  requires  that  the  program  manually 
switch  the  user  area  by  calling  the  BDOS. 
I  think  a  little  extra  work  should  have 
gone  into  allowing  a  program  to  pass  an 
extended  FCB  address  to  the  BDOS  when 
a  file  is  opened.  This  extended  FCB  would 
contain  all  the  additional  information 
necessary  to  interface  to  the  new  features 
that  I  have  already  mentioned,  plus  the 
user  number.  Better  yet,  instead  of  a  user 
number,  how  about  using  an  8 -character 
text  name  like  the  file  name? 

Making  comparisons  between  differ¬ 
ent  operating  systems  is  usually  like  com¬ 
paring  apples  to  oranges,  but  I  want  to 
point  out  how  files  are  handled  on  another 
system  that  I  use  daily.  To  protect  the 
innocent  I  will  call  this  new  system  Alpha. 
Alpha  is  a  Z80-based  computer  with  64K 
of  memory.  The  resident  operating  sys¬ 
tem  requires  approximately  10K,  and  the 
only  transient  part  of  the  system  is  the 
operator  interface,  which  is  equivalent  to 
CP/M’s  console  command  processor.  The 
only  place  that  my  comparison  begins  to 
break  down  is  that  Alpha  has  a  separate 
Z80-based  processor  that  handles  all  disk 
I/O.  I  think  my  analysis  still  holds  because 
CP/M  Plus  requires  a  minimum  of  96K  if 
you  want  to  use  the  extended  features. 
In  Alpha’s  case,  this  would  also  be  enough 
to  hold  all  the  disk  logic. 

A  file  specification  on  Alpha  is  con¬ 
tained  in  two  control  blocks.  The  first  is 
called  a  “file  control  block”  and  is  used 
for  various  pointers  and  general  parameter 
passing.  A  two-byte  area  of  the  FCB 
points  to  another  control  block,  the  “file 
name  block.”  Contained  in  the  FNB  are 
all  the  file’s  attributes  in  text  form.  In¬ 
cluded  are  eight  characters  for  the  file  set 
name  (equivalent  to  user  area),  eight  char¬ 
acters  for  the  file  name,  and  eight  more 
characters  for  the  file  extension.  Follow¬ 
ing  this  information  is  a  complete  descrip¬ 
tion  of  the  file.  This  includes  record  length, 
read  and  write  passwords,  and  some  other 
control  information  which  isn’t  germane 
to  this  discussion.  When  the  program 
wants  to  open  a  file,  the  FCB  address  is 
loaded  into  a  register  and  a  command 
code  is  placed  into  another.  A  call  is  made 
to  the  operating  system  through  a  restart 
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instruction,  and  away  you  go. 

If  it  sounds  simple,  it  is.  Take,  for 
example,  the  command  line  necessary  to 
assemble  a  program: 

ASM  BLUM -PROGRAM. ASM 

A  few  moments  later  the  BLUM- 
fileset  contains  the  assembler’s  output 
even  though  I  was  logged  into  the  TEMP- 
fileset. 

I  have  worked  on  a  number  of  com¬ 
puters  over  the  years  and  Alpha  is  my 
favorite.  The  real  surprise  comes  when 
one  considers  Alpha’s  origin.  Until  Alpha’s 
operating  system  was  far  enough  along  in 
the  development  cycle  to  stand  alone,  it 
was  run  under  CP/M.  Even  after  a  few 
years  of  refinement,  there  are  a  number 
of  CP/ M’s  operational  features  still  being 
used.  Of  course,  I  understand  that  a  lot  of 
things  can  be  done  when  designing  a  new 
system  that  can’t  be  done  when  modify¬ 
ing  an  existing  one  because  of  compati¬ 
bility  problems.  Still,  I  think  a  lot  can  be 
accomplished  if  the  motivation  exists.  I 
am  sure  that  this  discussion  won’t  teach 
DR  anything  new;  I  have  met  a  few  of 
their  people  and  they  are  sharp.  But  like 
so  much  else  in  this  business,  decisions 
are  based  on  market  potential.  And  as 
long  as  the  semiconductor  manufacturers 
continue  to  bring  out  new  and  improved 
processors  every  couple  of  years,  there  is 
little  time  left  to  do  anything  but  convert 
the  existing  systems.  Well,  as  I  have  said 
before,  that’s  the  state  of  the  art. 

A  Point  Well  Taken 

As  I  was  putting  the  final  touches  on 
this  month’s  column,  I  received  a  note 
from  a  reader  complaining  about  the  ap¬ 
parent  lack  of  proofreading  of  the  twittle 
subroutine  that  I  ran  a  couple  of  months 
ago.  He  found  the  word  “asterisk”  mis¬ 
spelled  in  the  comments  describing  the 
program.  I  must  admit  that  my  first 
impression  was  that  he  was  being  rather 
nit -picky,  but  after  a  moment’s  thought 
(it  takes  that  long  for  my  defense  mecha¬ 
nism  to  readjust),  I  decided  that  he  had 
a  valid  point.  To  the  eyes  of  many,  words 
are  like  notes  to  the  ears  of  a  musician.  I 
am  not  an  artist,  but  I  am  aggravated  by  a 
fuzzy  radio  station  or  a  scratched  record; 
my  reader  found  a  misspelled  word  to  be 
offensive  to  his  eyes.  I  apologize  for  the 
inexcusable  error  and  will  pay  more 
attention  to  detail  in  the  future. 

DRI  Patch  3  -  SUBMIT.COM 

Products  Affected:  CP/ M  2.2 

Copyright  ©  Digital  Research,  Inc.  1982. 
All  rights  reserved.  Used  with  permission 
of  Digital  Research,  Inc.  Text  adapted 
from  the  original. 

Error  Description:  If  drive  A  is  not 
the  default  drive  when  you  run  the  SUB¬ 
MIT  program,  the  $$$.SUB  file  is  created 


on  the  currently  logged -in  disk.  There¬ 
fore,  you  cannot  run  a  SUBMIT  job  from 
any  other  drive  than  A.  (This  occurs 
because  the  CCP  will  only  search  drive  A 
for  the  $$$.SUB  file.)  After  you  make 
the  changes  shown  in  Listing  One  (page 
94),  the  system  will  always  create  the 
$$$.SUB  file  on  drive  A. 

Patch  Procedure:  Make  a  back-up 
copy  of  SUBMIT.COM  before  you  use 
DDT  to  make  the  changes  in  Listing  One. 

SKIPNIF  —  Last  But  Not  the  Least 

Last  month  David  Kirkland  shared 
with  us  his  method  of  speeding  up  SUB¬ 
MIT  file  truncation.  When  he  submitted 
those  valuable  comments  he  also  included 
his  version  of  the  original  SKIPIF  program 
written  by  John  Ramsey.  Dave’s  program, 
SKIPNIF,  allows  one  extra  parameter  on 
the  command  line  to  specify  how  many 
records  from  the  SUBMIT  file  are  to  be 
skipped.  This  is  a  valuable  addition  to  an 
already  excellent  set  of  SUBMIT  file  con¬ 
trol  routines.  I  think  this  brings  the  sub¬ 
ject  of  SUBMIT  file  processing  to  a  logical 
conclusion.  By  using  the  many  routines 
that  have  been  published  in  DDJ  over  the 
past  year,  you  can  achieve  a  substantial 
level  of  control  over  how  SUBMIT  files 
are  processed.  A  complete  listing  of  Dave’s 
SKIPNIF  program  can  be  found  in  Listing 
Two  (page  94). 

■■J 

(Listings  begin  on  page  94) 
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CP/M  Exchange  (Text  begins  on  page  92) 

Listing  One 


A>DDT  SUBMIT.COM 
DDT  V2.2 
NEXT  PC 
0600  0100 
-D5BB 

05BB  00  24  24  24  20  .$$$ 

05C0  20  20  20  20  53  55  42  00  00  00  1A  1A  1A  1A  1A  1A  SUB... 

05D0  1A  1A  1A  1A  1A  1A  1A  1A  1A  1A  1A  1A  1A  1A  1A  1A  . 


-S5BB 
05BB  00  1 
05BC  24  . 

-GO 

A>S  AVE  5  SUBMIT.COM  End  Listing  One 


Listing  Two 


SKIPNIF  —  conditionally  skip  n  commands  within  a  sumbit  file 
written  by  David  Kirkland  i/12/83 

based  on  Don  Wright's  QUITIF  (DDJ  No.  71,  Sept  1982  at  8,  14) 


revised 

6/31/83 

t  o 

incorporate 

the 

"zero"  option,  based  on 

John  C  . 

Ramsey ' 

s  SKIPIF 

(DDJ  No 

N 

00 

Aug  1983  at  1  00-07  )  . 

Usage 

SKIPNIF 

Amb  i  g 

f  n 

n 

skip 

i  f 

f  n 

i s  amb i g  uo  u  s 

SKIPNIF 

Exists 

f  n 

n 

skip 

i  f 

f  n 

exists 

SKIPNIF 

Missing 

£  n 

n 

skip 

i  f 

f  n 

does  not  exist 

SKIPNIF 

Null  C 

f  n 

3  n 

skip 

i  f 

£  n 

not  specified  not  exist 

SKIPNIF 

Zero 

f  n 

n 

skip 

i  f 

f  n 

has  zero  length  or  does  not  exist 

On  1 y  the 

first 

character 

of  the 

f  i 

r  s  t 

keyword  (the  AMBIG  or  EXISTS  or 

whatever)  is  checked  If  an  invalid  keyword  is  entered,  the 
n  commands  will  be  unconditionally  skipped 


, 

Th  i  s 

code  written  for  Ithaca  Intersystems  IASM  assembler;  note 

1 

that 

"cci r"  is 

what  most  people 

call  "cpir",  and  "ccdr"  is  "cpdr" 

t  p  a 

equ 

0  1  00h 

b  d  o  s 

equ 

0  0  0  5  h 

f  cbl 

equ 

0  0  5  ch 

;  first 

fcb  prepared  by  CCP 

name  1 

equ 

f  cb 1  +  1 

;  start 

of  filename  of  fcbl 

f  cb2 

equ 

0  0  6  ch 

name  2 

equ 

f cb2+l 

cmd  t  a  i  1 

equ 

0  0  8  0  h 

drive 

equ 

'  M  ' 

;  drive 

on  which  5 S $  SUB  file  resides 

; 

;  (  '  A  ' 

for  no  rma 1  folk) 

;  BDOS 

codes 

94 

776 
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Pr  t  S  t  r 

equ 

9 

Op  en 

equ 

1  5 

Close 

equ 

1  6 

S  r  ch 1 s  t 

equ 

1  7 

Erase 

equ 

1  9 

Read 

equ 

2  0 

s  k  i  p  i  f 

o  r  g 

t  p  a 

;  first 

parse  c  o mm  and 

line 

by 

;  -  d  e  t 

ermining 

NSk  i  p 

,  the 

numb  e  r 

of  lines  to  skip  if  condition  sati 

s  f  e  d 

;  -  ensuring  that  the 

c  o  n  t 

e  n  t  s  of 

f  c  b  2  at 

6c  contain  the  fn  argument 

and 

;  no  t 

the  NS  k 

ip  a  r  g  ume  n  t 

(this 

probl em 

occurs  when  the  command  is 

; 

ski pn  i  f 

null 

NSk  i  p 

;  i  e 

.  ,  wh  e  n 

the  f  n 

a  r  g  ume  n  t  a  c 

t  u  a  1  I  y  i 

s  not  entered  and  the  skip 

sh  o  u  1  d 

be  executed) 


skip 


1  x  i 

h , cmd  tail 

mo  v 

c  ,  m 

;  length  of  command  line 

mv  i 

b  ,  0 

dad 

b 

;  hi  points  to  last  character 

in  command 

i  n  x 

h 

mv  i 

m ,  1 

' 

;  mark 

end  of  command  line  wi 

t  h  space 

over  1 

‘NSk ip", 

the  last 

a  r  g  ume  n t 

on  command  line 

call 

s  c  a  nb  1 

;  scan 

off  trailing  blanks 

line 


c  c  d  r 
push 


scan 

save 


b  a  c  kwa  r  d  s 
for  later 


until  a  space  reached 


;  now  skip  back 
call 
ccdr 

i  now  mo  v  e  back 
,  AMBIG  or  NULL 
;  £n  entered, 
call 
mo  v 
ora 
j  n  z 

ma  t  c  h  rav i 

s  t  a 
imp 


over  the  next  to 
s  c  a nb 1 


once  mo  r  e 
o  r  wh  atever 
there  will  be 
scanb  1 
a  ,  b 
c 

DoNum 

a  ,  '  ' 

name  2 
DoNum 


last  a  r  g ,  wh i c  h  is 
find  end  of  next 
find  start  of  the 


if  only  two  a  r  g  s  , 

a  r  g  to  ma  k  e  f  c  b  2 


Normally,  there  will  be 
But  in  our  special  ca 
nothing  left 


thr ow  away  e  x 

t  r  a 

are  there  any 

c  h  a 

command  line? 

i  f 

two  a  r  g  umen  t  s 

g  i  v 

"£n"  if  present 
a  r  g 
a  r  g 

one  argument  left,  the 
se  of  NULL  wi th  no 

blanks 

racters  unprocessed  in  the 
not,  then  there  were  only 
en  on  the  co  mm  and  line 

add  a  blank  for  the  second 
null 


;  scanb 1  scans 

b  a  c  kwa  r  d  s  over 

the 

c  omma  nd  line 

discard 

;  wh  e  n 

a  nonblank  character  1 

s  encountered, 

i  t 

stops 

;  h  -  > 

s  t  r  ,  be 

=  length  r  ema i 

n  i  ng  ; 

,  return  wi 

t  h 

hi  -  >  f 

s  c  anb  I 

mo  v 

a  ,  b 

see  if  any 

c  h 

a  r  a  c  t  e  r 

ora 

c 

r  z 

; 

none  left 

mv  i 

a  ,  '  ' 

scnLp 

emp 

m 

i 

*  h  1  '  ' 

rnz 

d  c  x 

h 

; 

next  cha  r 

d  c  x 

b 

/ 

count  d  own 

ing  blanks; 
irst  nonb lank 
s  r  ema  i  n 


(Continued  on  next  page) 
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CP/M  Exchange  (Listing  continued,  text  begins  on  page  92) 

Listing  Two 


j mp  s  c  a nb  1 

;  PROCESS  DECIMAL  NUMB ER- -mo d i f i e d  from  ZCPR 

I 

DoNum 

pop 
i  nx 
i  n  x 

;  convert  the 
;  at  N2  Skip 
mv  i 

NUMl  : 

MOV 
CPI 
JZ 
I  NX 
SUI 
CPI 
JNC 
MOV 
MOV 
RLC 
RLC 

RLC 


ADD 

C 

; CHECK  FOR  RANGE  ERROR 

JC 

NUMERR 

ADD 

C 

; CHECK  FOR  RANGE  ERROR 

JC 

NUMERR 

ADD 

D 

; NEW  VALUE  =  OLD  VALUE  *  10  +  DIGIT 

JC 

NUMERR 

; CHECK  FOR  RANGE  ERROR 

MOV 

C  ,  A 

; SET  NEW  VALUE 

i  up 

NUMl 

; do  next  digit 

/ 

NUMERR : 

;  come  here  if  number  invalid 

mv  i 

c  ,  P  r  t  S  t  r 

I  x  i 

d , NE  r  rMsg 

call 

b  do  s 

ret 

;  come  here  once  number  finished 

NUM2  : 

MOV 

A  ,  C 

; G ET  ACCUMULATED  VALUE 

s  t  a 

N2  Skip 

;  store  the  value  for  later 

;  now  actual  ly 

d o  wh at  the 

caller  asked  for: 

Ida 

name  1 

;  first  character  of  the  AMB I G  or  EXISTS  or 

1  x  i 

h , name  2 

c  p  i 

■  A  1 

3  * 

amb  i  g 

c  p  i 

1  E  1 

3  * 

exists 

c  p  i 

'  M  * 

3  * 

mi  s  s  i  ng 

c  p  i 

’  N  ’ 

3  ^ 

null 

h 

h 


h 

;  hi  points  to  first  char 

i  n 

numb  e  r 

\  c i ma I  numb  e  r 

pointed  to  by  hi  into  binary 

and 

store 

c  ,  0 

, C= ACCUMULATED  VALUE  set 

to  zero 

A  ,  M 

iGET  CHAR 

1  1 

; DONE  IF  *  which  marks 

end 

o  f  numb  e  r 

NUM2 

H 

; PT  TO  NEXT  CHAR 

■  0  ' 

iCONVERT  TO  BINARY  (ASCII 

0-9 

TO  BINARY) 

1  0 

.ERROR  IF  >=  10 

NUMERR 

D  ,  A 

.DIGIT  IN  D 

A  ,  C 

.NEW  VALUE  =  OLD  VALUE  * 

1  0 

98 
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c  p  i 

j  z 


'  Z  ' 

zero 


;  if  none  of  the  above,  fall  through  and  skip 


;  skip 
skip 


n  o  t  n  e  g 


,  abort 
amb  i  g 


;  abort 
exists 


;  abort 
mi s  s i ng 


;  abort 
null! 


over  next  N2Skip  commands 

in  9  99 SUB 

mv  i 

c  ,  Open  ; 

open  9  9  9  . SUB 

1  x  i 

d  ,  subf  i  1  e 

call 

bdo  s 

i  n  r 

a 

check  if  9  $  9. SUB  exists 

r  z 

f 

if  not,  return 

1  x  i 

h,subfile+14 

mv  i 

m  ,  0 

zero  the  S2  byte  of  the 

fcb  to  force  a  write 

1 

of  the  modified  fcb  back 

to  the  directory 

1  d  a 

N2Sk  i  p 

mo  v 

c  ,  a 

i  n  x 

h 

mo  v 

a  ,  m  ; 

decrement  the  number  of 

records  in  999  SUB 

sub 

c  i 

by  N2 Sk i p 

ip 

no  t  ne  g 

x  r  a 

a  ; 

if  skip  by  more  than  in 

file,  use  zero 

mo  v 

m  ,  a 

mv  i 

c  ,  C  1  o  s  e 

close  9 9 9 . SUB  to  rewrite 

the  mo  dified  fcb 

1  X  1 

d, subfile 

call 

b  d  o  s 

rav  i 

c  ,  P  r  t  S  t  r  ; 

tell  the  user  what  we've 

done 

1  x  i 

d , sk i pmsg 

call 

b  d  o  s 

x  r  a 

a  •  ; 

zero  a  and  set  flags  for 

zero/missing 

ret 

if  2d 

p  a  r m  amb i g  uo  u  s 

rav  i 

a  ,  '  ?  ' 

1  x  i 

b  ,  1  1 

c  c  i  r 

;  cpir  for  people  with  normal  assemblers 

J  z 

skip 

ret 

if  file  exists 

call 

search 

3  n  z 

skip 

ret 

if  f  i 

le  missing 

call 

search 

rni 

jmp 

skip 

if  2d 

p  a  rm  nu 1  1 

mv  i 

a  ,  '  ' 

cmp 

m 

r  n  z 

1  x  i 

h , name  2  +  8 

cmp 

m 

rnz 

Ida 

f  cb2 

ora 

a 

100 
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CP/M  Exchange  (Listing  continued,  text  begins  on  page  92) 

Listing  Two 


,  abort 
zero 


,  search 
search 


N2Sk  i  p 

ski pms  g 
NErrMsg 
subfile 


mi 

;  d:  given  without  more 

jmp 

skip 

if  2d 

pare  is  a  zero 

length  file 

call 

mi s  s i ng 

;  if  file  does  not  exist,  its  deemed  zero  length 

r  z 

;  if  so,  missing  has  skiped  N2Skip 

records  in 

;  $$$.SUB,  so  now  we  return  to  the 

CCP 

mv  i 

c  ,  Op  en 

1  x  i 

d  ,  f  cb2 

call 

bdo  s 

;  open  the  specified  file 

mv  i 

c  .Read 

1  x  i 

d , f cb2 

call 

b  d  o  s 

i  try  to  read  the  first  record 

ora 

a 

r  z 

;  read  was  OK,  so  not  zero  length, 

don’t  skip 

i  mp 

skip 

i  read  failed,  zero  length 

for 

first  to  see  if 

any 

file  exists  to  match  fcb 

mv  i 

c.Srchlst 

1  x  i 

d , f cb2 

call 

b  d  o  s 

i  n  r 

a 

;  adjust  flags:  Z  <->  not  found 

ret 

db 

0 

db 

"Next  command  s  skipped  ",13,10,  '$' 

db 

"Illegal  numb  e  r 

to  skip", 13, 10, 'S' 

db 

drive+l-'A' , 

'  $  $  s 

SUB" , 0 , 0 , 0 , 0 

End  Listing 
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7  6-BIT  SOFTWARE  TOOLBOX 


by  Ray  Duncan 


Version  2.0  of  MS-DOS  was  enhanced 
with  some  40  new  function  calls  for  use 
by  application  programs.  These  provide 
support  for  the  hierarchical  directories, 
device-independent  I/O,  and  memory 
allocation.  Most  of  them  are  rather  radical 
departures  from  the  CP/M-ish  origins  of 
MS-DOS  and  show  a  clear  tendency  to¬ 
ward  providing  a  Unix-like  environment. 

In  the  process  of  preparing  a  PC-DOS 
programmer’s  reference  book  for  publica¬ 
tion  next  year,  I  have  been  trying  each  of 
the  new  functions  out  in  turn  by  writing 
small  assembly  language  utilities.  When  I 
reached  function  4BH,  called  EXEC,  I  was 
especially  intrigued.  EXEC  is  designed  to 
allow  an  application  program  (which  we 
may  call  the  “parent”)  to  load  and  exe¬ 
cute  any  other  program  from  the  disk, 
then  regain  control  when  the  “child”  is 
finished.  The  parent  can  pass  a  consider¬ 
able  amount  of  information  to  the  child 
in  the  form  of  a  command  line,  default 
File  Control  Blocks,  and  a  set  of  strings 
called  the  “environment.”  Similarly,  the 
child  can  pass  an  exit  code  back  to  the 
parent  when  it  finishes  its  work. 

The  child  program  can  in  turn  load 
other  programs,  and  so  on  through  many 
levels  of  control  until  you  run  out  of 
memory.  This  function  has  plenty  of  uses 
even  in  a  single-tasking,  single-user 
operating  system.  For  example,  you  could 
write  your  own  screen-oriented,  menu- 
driven  command  processor  which  would 
become  the  user’s  interface  —  one  would 
never  need  to  learn  the  more  complex 
commands  like  MODE,  CHDIR,  and 
PATH  (the  same  thing  could  be  accom¬ 
plished  with  a  batch  file  but  it  would  run 
much  slower).  Alternatively,  you  could 
load  a  second  copy  of  the  native  Command 
Line  Processor  (COMMAND.COM),  and 
let  it  run  under  the  control  of  your  pro¬ 
gram,  rather  than  directly  on  top  of 
MS-DOS. 

In  a  multi-tasking  environment  such 
as  we  expect  to  see  in  MS-DOS  3.0,  this 
function  will  be  even  more  useful  and  will 
undoubtedly  be  elaborated  with  several 
additional  features.  Under  such  an  operat¬ 
ing  system,  a  parent  task  can  “spawn” 
any  number  of  child  tasks,  which  can 
execute  concurrently  and  asynchronously, 
and  communicate  by  means  of  queues, 
semaphores,  and  pipes. 

Well,  you  say,  pie  in  the  sky  is  all 
very  nice,  but  why  is  the  EXEC  function 
getting  so  much  attention  in  this  maga¬ 
zine  column?  The  answer  is,  of  course, 


that  when  I  tried  to  actually  use  the  func¬ 
tion  I  ran  into  any  number  of  glitches  and 
hazy  spots  in  the  documentation. 

The  “official”  definition  of  the 
EXEC  function,  slightly  boiled  down,  is 
given  in  Figure  1  (below).  It  looks 
straightforward  enough,  if  you  ignore  the 
problem  of  what  format  the  parameter 
block’s  DWORD  addresses  might  be  in. 
The  documentation  notes  that  “when 
your  program  received  control,  all  availa¬ 
ble  memory  was  allocated  to  it.  You  must 
free  some  memory  (see  call  4 AH)  before 
EXEC  can  load  the  program  you  are 
invoking.  Normally,  you  would  shrink 
down  to  the  minimum  amount  of  memory 
you  need,  and  free  the  rest.” 


The  manual  goes  on  to  state  that  all 
open  files  of  the  parent  are  duplicated  in 
the  newly  created  child  task.  Also  inher¬ 
ited  from  the  parent  is  some  new  creature 
called  an  “environment  block,”  which  is 
rather  vaguely  defined  as  a  series  of  ASCII 
strings  in  the  form  “NAME=  parameter.” 

Each  of  the  strings  in  the  environment 
block  is  terminated  by  a  zero  byte,  and 
the  whole  set  of  strings  is  terminated  by 
an  additional  zero  byte.  The  environment 
always  starts  on  a  paragraph  boundary, 
and  its  segment  address  is  ultimately 
placed  at  offset  2CH  of  the  Program  Seg¬ 
ment  Prefix.  You  can  either  leave  that  slot 
in  your  EXEC  parameter  block  as  zero 
(in  which  case  the  child  will  acquire  the 


Call  with : 

AH  =  4BH 

AL  =  load  type  (see  below) 

DS  =  segment  of  ASCI  I Z  path  &  program  name  string 

DX  =  offset  of  ASCI  I Z  path  &  program  name  string 

ES  =  segment  of  parameter  block 

BX  =  offset  of  parameter  block 

Returns: 

Carry  Flag  set  if  unsuccessful  call.  AL  =  error  code. 

Carry  Flag  cleared  if  successful  call.  Except  for  CS  and  IP,  all  other 
registers,  including  the  stack  pointers,  are  destroyed. 

Load  type  =  0  :  Load  and  execute  program.  "A  program  segment  prefix  is 
established  for  the  program  and  the  terminate  and  control /Break  addresses 
are  set  to  the  instruction  after  the  EXEC  call." 

Parameter  block  format: 

WORD  segment  address  of  environment  block 
DWORD  pointer  to  command  line  to  be  placed  at  new  Program 
Segment  Prefix  +  80H 

DWORD  pointer  to  default  FCB  #1,  to  be  passed  at  new  Program 
Segment  Prefix  +  5CH 

DWORD  pointer  to  default  FCB  #2,  to  be  passed  at  new  Program 
Segment  Prefix  +  6  CH 

Load  type  =  3  :  Load  overlay.  Does  not  create  a  Program  Segment  Prefix,  and 
does  not  begin  execution  of  the  overlay. 

Parameter  block  format: 

WORD  segment  address  where  file  will  be  loaded 
WORD  relocation  factor  to  be  applied  to  the  image 

Figure  1. 

Specification  of  arguments  and  results  of  MS-DOS  EXEC  function  4BH. 
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same  environment  block  as  your  calling 
program),  or  you  can  provide  a  pointer  to 
your  own  set  of  strings.  The  manual  non¬ 
chalantly  adds  that  the  maximum  size  of 
the  environment  block  is  32  Kbytes. 

This  zinger  introduces  a  whole  new 
set  of  mysteries.  What  in  the  world  could 
the  environment  block  possibly  contain 
that  could  be  as  large  as  32  Kbytes?  Fur¬ 
thermore,  the  manual  explicity  states  that 
the  environment  block  for  any  given  pro¬ 
gram  is  static,  implying  that  if  more  than 
one  generation  of  child  programs  is  resi¬ 
dent  in  RAM,  each  one  might  have  a  dis¬ 
tinct  and  separate  copy  of  these  poten¬ 
tially  32  Kbyte  rascals  floating  around 
somewhere.  My  goodness! 

Paging  through  the  PC- DOS  manual 
in  search  of  further  enlightenment,  1 
found  some  help  in  appendix  E  which 
stated:  “the  environment  built  by  the 
command  processor  (and  passed  to  all 
programs  it  invokes)  will  contain  a  COM- 
SPEC  string  at  a  minimum  (the  parameter 
on  COMSPEC  is  the  path  used  by  DOS  to 
locate  COMMAND.COM  on  disk).  The 
last  PATH  and  PROMPT  commands  will 
also  be  in  the  environment,  along  with 
any  environment  strings  entered  through 
the  SET  command.” 

Thus,  the  environment  block  contains 
at  most  three  strings  that  actually  mean 
something  to  MS-DOS  (PATH=,  COM- 
SPEC=,  and  PROMPT=).  Any  other  strings 
found  in  the  block  by  an  application  pro¬ 
gram  were  placed  there  for  its  information 
by  a  SET  command  issued  by  the  operator 
or  by  another  application  program  and 
have  no  effect  on  the  behavior  of  the  op¬ 
erating  system  proper.  Loading  a  dummy 
COM  file  under  the  control  of  DEBUG, 
getting  the  pointer  from  offset  2CH  in 
the  Program  Segment  Prefix,  and  dumping 
out  memory,  I  found  that  the  “default” 
environment  in  my  system  is  indeed 
only  the  two  strings  “PATH  =  ”  and 
“COMSPEC=A:\COMMAND.COM.”  Not 
so  formidable  after  all. 

The  major  remaining  puzzle  turned 
out  to  be  the  SETBLOCK  function  (MS- 
DOS  function  4AH),  which  your  program 
is  supposed  to  use  to  “shrink  down”  the 
amount  of  space  allocated  to  it  before 
using  EXEC  to  load  another  program. 
The  manual  says,  “on  entry,  ES  contains 
the  segment  of  the  block,  BX  contains  the 
new  requested  block  size  in  paragraphs.” 
But  when  the  “block”  refers  to  the  applica¬ 
tion  program  itself,  and  not  to  some  piece 
of  RAM  it  requested  later,  what  segment 
to  use:  the  segment  of  the  Program  Seg¬ 
ment  Prefix  or  the  base  of  the  Code  Seg¬ 
ment?  Or  does  “block”  actually  refer  to 
some  kind  of  memory  descriptor  parame¬ 
ter  block  buried  in  COMMAND.COM? 

Attempts  to  test  this  out  with  the 
Debugger  were  completely  baffling,  every 
attempt  resulting  in  an  error  code.  It  turns 
out  that  since  the  Debugger  essentially 
“owns”  all  of  memory  and  loads  your 
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program  via  its  own  mechanisms,  a  SET- 
BLOCK  call  by  a  program  running  under 
the  control  of  DEBUG  is  illegal  by  defini¬ 
tion  -  from  the  operating  system’s  point 
of  view,  it  is  trying  to  modify  a  memory 
allocation  that  does  not  “belong”  to  it. 
In  any  event,  the  “segment  of  the  block” 
that  should  be  fed  to  function  4AH  is  the 
Program  Segment  Prefix. 

Finding  the  number  of  paragraphs  to 
“shrink”  your  program’s  memory  alloca¬ 
tion  down  to  is  also  a  little  tricky,  at  least 
for  EXE  files.  You  might  think  that  you 
can  simply  make  an  Equate  to  an  address 
called  Program_End,  put  that  in  a  data 
segment  at  the  end  of  your  program,  and 
load  that  segment  address  into  BX  at  exe¬ 
cution  time  with  the  aid  of  the  GROUP 
modifier,  thereby  letting  the  Linker  and 
Loader  do  all  the  work. 

Unfortunately,  that  method  won’t 
work  -  at  least  not  all  the  time.  The 
Linker  moves  all  the  declared  segments 
around  to  suit  its  own  purposes,  and  the 
physical  order  of  segments  in  your  source 
code  doesn’t  usually  correspond  to  the 
order  of  segments  in  the  resultant  EXE 
file.  The  best  way  I  have  figured  out  to 
get  the  total  size  of  the  program  at  run¬ 
time  is  to  put  an  equate  to  “Program- 
End”  into  another  module,  which  is 
separately  assembled,  and  reference  it 
with  an  EXTRN  in  your  main  program. 
At  link  time,  specify  the  module  contain¬ 
ing  the  “Program_End”  equate  as  the 
last  in  the  list  of  OBJ  files. 

Of  course,  you  can  also  “cheat”  by 
simply  assembling  and  Unking  the  pro¬ 
gram,  looking  at  the  size  of  the  EXE  file 
in  the  directory  listing,  and  then  reassem¬ 
bling  the  program  with  the  correct  size  in 
the  code  as  a  Uteral  value.  This  assumes 
that  all  data  areas  used  by  the  program 
are  embedded  as  declared  constants  and 
variables.  An  approach  like  this  could 
cause  you  trouble  later  if  you  modify  the 
program  in  a  way  that  increases  its  size, 
then  forget  to  update  the  literal  too. 

To  keep  the  amount  of  painful  inter¬ 
action  between  the  EXEC  function  and 
DDJ  readers  to  a  minimum,  I  am  publish¬ 
ing  herewith  a  very  detailed  example  pro¬ 
gram  named  FXN4BH  (see  the  listing, 
below),  using  EXEC  to  load  the  MS-DOS 
utility  CHKDSK.COM,  that  is  guaranteed 
to  work.  It  requires  that  both  FXN4BH.- 
EXE  and  CHKDSK.COM  be  present  on 
the  “current”  or  default  disk  drive. 
FXN4BH  can  fail  if  there  is  not  enough 
room  above  it  in  RAM  to  load  and 
execute  CHKDSK.COM,  or  if  the  transi¬ 
ent  portion  of  COMMAND.COM  in 
highest  RAM  (which  contains  the  actual 
loader)  has  been  destroyed  and  there  is 
not  enough  free  memory  to  reload  it. 

■•J 
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16-Bit  Toolbox  Listing  (Text  begins  on  page  102) 


1 

2 

3 

4 

5 

6 

7 

8 
9 


naae  FXN4BH 

page  55,132 

title  'FXN4BH  —  deao  PC-DOS  EXEC  function' 

FXH4BH  —  deaonstrate  use  of  the 
PC-DOS  2.0  EXEC  function  call  4BH 

Copyright  (c)  1983  by  Ray  Duncan 


10 

=  OOOD 

cr 

equ 

Odh  ; ASCII  carriage  return 

11 

=  000ft 

If 

equ 

Oah  ; ASCII  line  feed 

12 

i 

13 

0000 

cseg 

segient 

para  public  'CODE' 

14 

J 

15 

assuae 

csicseg, ds: data, ss: stack 

16 

i 

17 

0000 

deio 

proc 

far 

18 

; at  entry  DS  t  ES  =  PSP 

19 

0000 

IE 

push 

ds  ; Save  address  for  final 

20 

0001 

33  CO 

xor 

ax, ax  ; FAR  RET  to  PC-DOS  on  stack 

21 

0003 

50 

push 

ax 

22 

;save  copy  of  SS: SP  for  use 

23 

; after  return  froa  overlay 

24 

0004 

2E:  8C  16  0050  R 

aov 

csiSTK_SEG,ss 

25 

0009 

2E:  89  26  0052  R 

aov 

cs:STK_PTR,sp 

26 

! 

27 

i Reserve  1000H  bytes  for 

28 

; this  loader  and  release 

29 

; the  rest  of  aeaory  for 

30 

;use  by  the  overlayed  prograa 

31 

000E 

BB  0100 

aov 

bx,100h  ;ES=segaent  of  PSP  of  loader 

(Continued  on  page  106) 
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16-Bit  Toolbox  Listing  (Listing  continued,  text  begins  on  page  102) 


32 

0011  B4  4A 

ROV 

ah,4ah  {Bi-paragraphs  to  reserve 

33 

0013  CD  21 

int 

21h 

34 

; sake  the  aessages  in  data 

35 

;segnent  addressable 

36 

0015  88  - R 

■ov 

ax,seg  DATA 

37 

0018  8E  D8 

aov 

ds,ax 

38 

001A  8E  CO 

■ov 

es,ax 

39 

{juap  it  aeiory 

40 

; de-al 1 ocati on  failed 

41 

001C  72  2A 

jc 

ALL0C_ERR 

42 

;print  leaory  successfully 

43 

{released 

44 

001E  BA  001E  R 

■ov 

dx, off set  NS62 

45 

0021  B4  09 

■ov 

ah, 9 

46 

0023  CD  21 

int 

21h 

47 

1 

48 

;noM  load  and  execute 

49 

;the  overlaid  prograe. 

50 

0025  BA  0OA4  R 

■ov 

dx, off set  P6HJIAHE 

51 

0028  BB  00B0  R 

■ov 

bx, off set  PARJLK 

52 

002B  B0  00 

■ov 

al  ,0 

53 

002D  B4  4B 

■ov 

ah , 4bh 

54 

002F  CD  21 

int 

21h 

55 

{restore  stack  pointers 

56 

;to  state  before  EXEC  call 

57 

0031  2E:  8E  16  0050  R 

■ov 

ss,cs:STK_SES 

58 

0036  2E:  8B  26  0052  R 

■ov 

sp,cs:STK_PTR 

59 

{Hake  data  segaent 

60 

{addressable  again 

61 

0038  88  — -  R 

■ov 

ax,seg  DATA 

62 

003E  8E  DB 

■ov 

ds,ax 

63 

{print  aessage  that  loader 

64 

{successfully  regained  control 

65 

0040  BA  0059  R 

■ov 

dx, off set  HSE3 

66 

0043  B4  09 

■ov 

ah, 9 

67 

0045  CD  21 

int 

21h 

68 

{non  exit  to  PC-DOS 

69 

0047  CB 

ret 

70 

71 

0048 

alloc_err: 

; coae  here  if  aeaory 

72 

{cannot  be  released 

73 

0048  BA  0000  R 

■ov 

dx, offset  HSG1 

74 

004B  B4  09 

■ov 

ah, 9 

75 

004D  CD  21 

int 

21h  {print  error  aessage  and 

76 

C?4F  CB 

ret 

{exit  to  PC-DOS 

77 

i 

78 

0050 

deao  endp 

79 

5 

80 

{these  two  variables  aust 

81 

j reside  in  Code  Segment  so 

82 

{that  they  are  addressable 

83 

{after  return  fro*  overlay. 
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84 

0050 

0000 

stk_seg 

dN 

0 

; original  SS  contents 

85 

0052 

0000 

stk _ptr 

dw 

0 

; original  SP  contents 

86 

1 

87 

0054 

cseg 

ends 

88 

89 

; declare  a  stack  area 

90 

; for  use  by  this  loader 

91 

0000 

stack 

segient 

para 

stack  'STACK' 

92 

; al 1  oh  64  bytes  in  this  case 

93 

0000 

40 

[ 

db 

64 

dup  (?) 

94 

?? 

95 

] 

96 

97 

0040 

stack 

ends 

98 

99 

{declare  data  segient  to 

100 

{contain  variables  and  tables 

101 

0000 

data 

segient 

para 

)ublic  'DATA' 

102 

i 

103 

0000 

0D 

Oft 

■sgl 

db 

cr 

.If 

104 

0002 

55 

6E 

61 

62 

6C 

65 

db 

'Unable  to  release  leiory. ' 

105 

20 

74 

6F 

20 

72 

65 

106 

6C 

65 

61 

73 

65 

20 

107 

6D 

65 

6D 

6F 

72 

79 

108 

2E 

109 

001 B 

0D 

0A 

24 

db 

cr 

110 

001E 

0D 

0A 

«sg2 

db 

cr 

,lf 

111 

0020 

4D 

65 

6D 

6F 

72 

79 

db 

'Heaory  above  loader  released,' 

112 

20 

61 

62 

6F 

76 

65 

113 

20 

6C 

6F 

61 

64 

65 

114 

72 

20 

72 

65 

6C 

65 

115 

61 

73 

65 

64 

2E 

116 

003D 

0D 

0A 

4E 

6F 

77 

20 

db 

cr 

If 

'Non  loading  CHKDSK. CON.' 

117 

6C 

6F 

61 

64 

69 

6E 

118 

67 

20 

43 

48 

4B 

44 

119 

53 

4B 

2E 

43 

4F 

4D 

120 

2E 

121 

0056 

0D 

0A 

24 

db 

cr 

If 

122 

0059 

0D 

0A 

■sg3 

db 

cr 

If 

123 

005B 

4C 

6F 

61 

64 

65 

72 

db 

'Loader  regained  control  froi  CHKDSK,' 

124 

20 

72 

65 

67 

61 

69 

125 

6E 

65 

64 

20 

63 

6F 

126 

6E 

74 

72 

6F 

6C 

20 

127 

66 

72 

6F 

6D 

20 

43 

128 

48 

4B 

44 

53 

4B 

2C 

129 

007F 

0D 

0A 

db 

cr, 

If 

130 

0081 

6E 

6F 

77 

20 

6D 

61 

db 

’noH  naking  final  exit  to  PC-DOS. ' 

131 

6B 

69 

6E 

67 

20 

66 

(Continued  on  next  page) 
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16-Bit  Toolbox  Listing  (Listing  continued,  text  begins  on  page  102) 


132 

69  6E  61  6C  20  65 

133 

78  69  74  20  74  6F 

134 

20  50  43  2D  44  4F 

135 

53  2E 

136 

00A1 

0D  0A  24 

db 

cr.lVf 

137 

i 

136 

(drive,  path,  and  naae  of  prograa 

139 

; to  be  loaded  and  executed. 

140 

00A4 

5C  43  48  48  44  53 

pgijiaie  db 

'\CHKDSK.C0H',0 

141 

4B  2E  43  4F  4D  00 

142 

■ 

1 

143 

00B0 

....  r 

parbl k  dN 

ENV1R  (segment  address  of 

144 

; environment  descriptor 

145 

a 

» 

146 

(full  address  of  coaaand  line 

147 

;to  be  passed  at  offset  80H 

148 

00B2 

00BE  R 

dN 

offset  CHD_L1NE  (in  overlaid 

149 

00B4 

....  R 

dN 

seg  CMD_L1NE  (program's  PSP 

150 

i 

151 

(full  address  of  default 

152 

(File  Control  Block  to  be 

153 

(passed  at  offset  5CH  in 

154 

00B6 

00C5  R 

dN 

offset  FCB1  (overlaid 

155 

0068 

....  R 

dN 

seg  FCB1  (program's  PSP 

156 

5 

157 

(full  address  of  default 

158 

(File  Control  Block  to  be 

159 

(passed  at  offset  6CH  in 

160 

00BA 

00EA  R 

dN 

offset  FCB2  (overlaid 

161 

00BC 

....  R 

dN 

seg  FCB2  (program's  PSP 

162 

i 

163 

(actual  command  line  tail 

164 

(to  be  passed  to  overlay 

165 

00BE 

04  20  2A  2E  2A  0D 

cmdjine  db 

4,'  *.»’,cr,0 

166 

00 

167 

• 

» 

168 

(first  default  FCB  to 

169 

00C5 

00 

fcbl  db 

0  ;be  passed  to  overlay 

170 

00C6 

0B  1 

db 

11  dup  1'?') 

171 

3F 

172 

1 

173 

174 

0081 

19  t 

db 

25  dup  <01 

175 

00 

176 

1 

177 

178 

179 

(second  default  FCB  to 

180 

00EA 

00 

fcb2  db 

0  ;be  passed  to  overlay 

181 

OOEB 

0B  [ 

db 

11  dup  ('  ') 

182 

20 

183 

1 

184 

110 
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185 

00F6  19  [ 

db 

25  dup  (0) 

186 

00 

187 

] 

188 

189 

• 

} 

190 

010F 

data 

ends 

191 

192 

; declare  separate  data 

193 

(segaent  to  contain 

194 

jenvironaent  descriptor 

195 

0000 

envir 

segaent 

para  'ENVIR' 

196 

a 

J 

197 

(Search  path  used  by  PC-DQS 

198 

; to  look  for  coaaands  or 

199 

(batch  Files  not  Found  in 

200 

0000  50  41  54  48  3D  00 

db 

'PATH=',0  (the  current  directory 

a 

f 

201 

202 

(Search  path  used  by  PC-D0S 

203 

(to  locate  COtWAND.CON 

204 

0006  43  4F  4D  53  50  45 

db 

' CQMSPEC=A: \C0NNAND. CON ' ,0 

205 

43  3D  41  3A  5C  43 

206 

4F  4D  4D  41  4E  44 

207 

2E  43  4F  4D  00 

208 

001D  00 

db 

0  (extra  0  byte  designates 

209 

(end  oF  environaent 

210 

001E 

envir 

ends 

211 

212 

end 

deao 

End  Listing 
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SOFTWARE  REVIEWS 


TRANSFORM 

Company:  MasterComputing,  Inc.,  P.O. 

Box  17442,  Greenville,  SC  29606 
Price:  $39.95 

Circle  Reader  Service  No.  121 
Reviewed  by  Michael  Favitta 

MasterComputing’s  (MCI)  TRANS¬ 
FORM  is  a  language  preprocessor  for 
Microsoft  BASIC  and  other  compatible 
BASIC’s.  It  translates  MCI’s  enhanced 
BASIC  syntax  (which  includes  block 
structured  statements)  into  Microsoft 
BASIC  5.X  syntax.  The  purpose  of 
TRANSFORM  is  to  allow  BASIC  pro¬ 
grammers  to  develop  programs  that  are 
easier  to  debug,  understand,  and  maintain, 
by  using  a  structured  source  language. 

TRANSFORM  is  designed  for  CP/M 
systems  that  have  48  K  of  memory.  Trans¬ 
lated  programs  will  run  under  MBASIC 
5.X  or  can  be  compiled  with  BASCOM 
5.3.  The  translator  is  distributed  on  an  8- 
inch  single-density  disk  along  with  a 
sample  program  and  a  utility  program 
named  SIFT. 

A  Structured  BASIC  Language 

MCI  has  made  three  changes  to  Micro¬ 
soft  BASIC  to  create  an  enhanced  version 
of  BASIC.  MCI  has  added  blocked  con¬ 
trol  structures,  an  INCLUDE  facility,  and 
replaced  line  numbers  with  labels. 

To  add  blocked  structures  to  BASIC, 
the  Microsoft  BASIC  statements  ON- 
GOTO  and  IF-THEN-ELSE  were  modified 
and  a  new  statement,  REPEAT-UNTIL, 
was  added.  The  syntax  of  all  other  state¬ 
ments  remains  'the  same.  The  end-of- 
block  sentinels,  ENDGOTO  and  ENDIF, 
were  added  to  the  standard  syntax  of  the 
ON-GOTO  and  IF-THEN-ELSE  state¬ 
ments.  The  translator  implements  the 
three  additional  statements  by  replacing 
MCI’s  blocked  structures  with  combina¬ 
tions  of  standard  Microsoft  IF-THEN  and 
GOTO  statements.  This  produces  an  inter¬ 
mediate  object  program  that  is  standard 
Microsoft  BASIC.  The  two  examples  in 
Table  I  (at  right)  show  how  the  IF-THEN- 
ELSE-ENDIF  and  REPEAT-UNTIL  state¬ 
ments  are  translated. 

Line  numbers  are  replaced  with  labels- 
in  the  TRANSFORM  source  language.  A 
label  is  any  combination  of  alphanumeric 
characters  up  to  255  characters  in  length 
that  is  preceded  by  the  character 
The  translator  generates  the  line  numbers 
that  are  required  by  Microsoft  BASIC 
when  the  intermediate  object  file  is 
created.  A  symbol  table  can  be  produced 


that  contains  the  label  to  line  number 
mapping.  A  restriction:  only  comments 
may  follow  a  label  definition,  since  the 
translator  turns  all  label  definitions  into 
REMarks  for  documentation  in  the  inter¬ 
mediate  object  program. 

MCI  added  an  INCLUDE  facility  to 
allow  any  file  that  contains  BASIC 
statements  to  be  copied  into  a  program. 
A  DEFINE  statement  may  be  used  in 
conjunction  with  an  INCLUDE  statement 
to  redefine  the  variable  names  in  the  in¬ 
cluded  source.  This  allows  a  programmer 
to  use  the  same  procedure  in  many  pro¬ 
grams,  or  several  times  in  a  single  program, 
without  modifying  the  variables  used  in 
the  procedure.  Since  all  BASIC  variables 
are  global,  using  a  facility  such  as  MCI’s 
INCLUDE  is  as  close  as  you  can  get  to 
having  local  procedures  in  BASIC.  The 
INCLUDE  statement  may  be  nested  up  to 
five  levels  deep. 

TRANSFORM  allows  a  programmer 
to  enable  and  disable  the  translator  from 
within  the  program.  Two  special  labels, 
@PREON  and  @PREOFF,  are  used  for 
this  purpose.  When  the  translator  is  dis¬ 
abled,  the  standard  Microsoft  BASIC  ON- 
GOTO  and  IF-THEN-ELSE  statements 
can  be  used.  @PREON  and  @PREOFF 


function  correctly  with  the  INCLUDE 
statement  by  only  affecting  the  level  of 
INCLUDE  at  which  they  were  specified. 

The  TRANSFORM  Translator 

The  TRANSFORM  translator  consists 
of  two  COM  files, TF.COM  andTFl.COM. 
To  invoke  the  translator  you  need  only 
enter  TF.  The  program  prompts  the  user 
for  all  information  that  is  needed  to  per¬ 
form  the  translation.  Most  options  have  a 
default  response  that  can  be  chosen  by 
entering  a  carriage  return.  Default  file 
name  extensions  of  PRE  and  BAS  are 
assumed  for  the  source  input  and  object 
files.  TRANSFORM  searches  for  the 
source  if  it  is  not  on  the  specified  drive. 
The  order  of  the  search  is  the  currently 
logged-in  drive,  followed  by  the  system 
drive.  TRANSFORM’S  processing  options 
include  line  number  and  increment  selec¬ 
tion  for  the  translated  source,  listing  and 
error  message  routing,  hardcopy  for¬ 
matting  information,  and  symbol  table 
creation. 

Once  file  name  and  option  selection 
is  complete,  TRANSFORM  begins  its  first 
pass  on  the  source  file.  This  pass  trans¬ 
lates  the  structured  BASIC  source  pro¬ 
gram  to  standard  Microsoft  BASIC.  The 


TRANSFORM  Source 

Translated  Object  Code 

IF  (condition)  THEN 

1000 

IF  NOT  (condition)  THEN  1200 

(block  of  statements) 

(block  of  statements) 

ELSE 

1190 

1200 

GOTO  1400 

REM 

(block  of  statements) 

(block  of  statements) 

ENDIF 

1400  REM 

REPEAT 

1000 

REM 

(block  of  statements) 

(block  of  statements) 

UNTIL  (condition) 

1200  IF  NOT  (condition)  THEN  1000 

Table  1 

Examples  of  how  the  IF-THEN-ELSE-ENDIF  and 

REPEAT-UNTIL  are  translated. 
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translator  may  be  interrupted  at  anytime. 
Once  interrupted,  you  may  continue, 
translate  a  different  source  file,  or  termi¬ 
nate  the  translator.  At  the  completion 
of  pass  one,  TRF.COM  is  loaded  and 
pass  two  begins.  This  pass  performs  all 
the  line  numbering  that  is  required  by 
Microsoft  BASIC.  When  the  translator  has 
finished,  an  intermediate  object  program 
has  been  created  which  can  be  loaded  by 
MBASIC  or  compiled  by  BASCOM. 

TRANSFORM  programs  must  be 
created  with  a  text  editor,  since  BASIC 
editors  always  require  line  numbers. 
Some  text  editors,  such  as  Wordstar,  set 
the  high  order  bit  on  certain  characters. 
This  causes  problems  for  the  translator, 
so  a  utility  named  SIFT  is  provided  to 
strip  off  all  the  high  order  bits  in  a  text 
file.  This  utility  is  not  needed  if  your  text 
editor  doesn’t  set  the  high  order  bit  on 
any  ASCII  characters. 


Documentation 

The  documentation  that  is  provided 
by  MCI  is  divided  into  two  sections,  a 
tutorial  and  a  user’s  manual.  The  tutorial 
demonstrates  how  the  translator  is  in¬ 
voked  and  describes  the  procedures  that 
are  needed  to  get  from  MCI-enhanced 
BASIC  to  Microsoft  BASIC.  An  addition¬ 
al  feature  in  the  tutorial  is  a  discussion  of 
structured  programming  and  how  it  can 
be  used  to  simplify  the  task  of  creating  an 
“error-free”  program.  As  an  example, 
the  tutorial  proceeds  step  by  step  through 
the  design  of  a  program  to  format  and 
print  BASIC  program  source  files.  The 
source  code  for  the  example  program  is 
included,  so  that  the  user  may  experi¬ 
ment  with  TRANSFORM  without  first 
having  to  write  a  program.  Besides  being 
the  basis  for  the  tutorial,  the  print  pro¬ 
gram  is  a  useful  utility. 

The  user’s  manual  is  a  logical  progres¬ 
sion  of  information  about  TRANSFORM. 
The  first  part  of  the  manual  contains 
general  information  on  the  purpose  of 
TRANSFORM  and  its  theory  of  opera¬ 
tion.  The  second  part  details  the  syntax 
of  all  aspects  of  MCI’s  enhanced  BASIC 
language. 


Reviewer's  Comments 

TRANSFORM  allows  a  programmer 
to  write  BASIC  programs  using  blocked 
control  structures  that  have  been  present 
in  other  high-level  languages  for  years. 
Ideally,  there  would  be  no  use  for  such  a 
product,  as  people  who  wished  to  write 
structured  programs  would  use  an  avail¬ 
able  high-level  language.  Unfortunately, 
due  to  the  number  of  years  Microsoft 
BASIC  has  been  around,  the  availability 
of  a  compatible  compiler,  and  the  costs 
associated  with  purchasing  several  lan¬ 
guage  processors,  this  product  does  serve 
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a  useful  purpose.  Many  CP/M  software 
products  also  require  Microsoft  BASIC, 
such  as  MCI’s  MCDISPLAY,  making  the 
use  of  a  structured  language  impossible. 

One  disadvantage  to  MCI’s  approach 
to  structured  BASIC  is  that  it  adds 
another  step  in  the  process  of  creating  an 
executable  program.  It  is  a  costly  step 
regarding  compile  time,  as  translating  a 
500-line  program  takes  between  eight 
and  ten  minutes.  There  is  also  potential 
for  problems  in  the  translated  source 
due  to  the  way  TRANSFORM  imple¬ 
ments  its  blocked  structures.  In  Microsoft 
BASIC  any  non-zero  expression  is  con¬ 
sidered  to  represent  the  true  condition 
for  an  IF  statement.  MCI  uses  “IF 
NOT(condition)  THEN”  as  part  of  the 
translation  for  each  of  the  blocked  struc¬ 
tures.  This  creates  the  restriction  that  all 
conditionals  used  by  the  blocked  control 
structures  must  evaluate  to  true  (minus 
one)  or  false  (zero).  Although  this  restric¬ 
tion  is  well-documented,  the  burden  is 
on  the  user  to  make  sure  that  it  is  fol¬ 
lowed. 

MCI’s  product  TRANSFORM  does 
work.  The  documentation  is  complete 
and  the  translator  is  easy  to  use.  If  you 
already  have  Microsoft  BASIC,  it  would 
be  difficult  to  find  a  structured  language 
interpreter  or  compiler  of  this  caliber  for 
$39.95. 


COMMX-PAC 

Company:  Hawkeye  Grafix,  23914  Mo¬ 
bile,  Canoga  Park,  CA  91307 
Computer  System:  CP/M  2.0  or  greater 
Price:  COMMX-PAC:  $150,  or  COMMX 

only:  $99 

Circle  Reader  Service  No.  123 
Reviewed  by  Gene  Head 

I  write  for  several  computer  maga¬ 
zines  and  have  a  listed  phone  number.  So 
I  suppose  I  get  more  than  my  normal 
share  of  phone  calls  from  individuals  with 
questions  about  microcomputers.  Eight 
out  of  ten  callers  are  requesting  help  get¬ 
ting  a  modem  working.  Seven  of  those 
eight  are  non-programming  types  trying 
to  get  some  version  of  Ward  Christensen’s 
MODEM  program  working.  For  many,  it 
is  a  simple  matter  to  set  a  program’s 
equates  to  a  serial  RS-232  status  and  data 
port  and  to  monitor  the  proper  status  bits 
For  just  as  many  this  task  is  impossible. 

Will  Pierce  at  Hawkeye  Grafix  has 
taken  on  the  task  of  delivering  a  modem 
communications  and  control  package  that 
is  factory  patched  to  run  without  change 
on  the  user’s  computer  system.  When  or¬ 
dering  COMMX-PAC,  the  user  specifies 
his/her  computer  and  modem,  and  Hawk- 
eye  does  the  rest.  The  purchaser  receives 
a  disk  with  programs  that  run  without  the 
need  for  any  adaptations.  Well  almost.  .  .  . 


The  package  I  ordered  for  my  IMSAI 
MIO  serial  I/O  card  was  delivered  with 
the  status  bit  logic  reversed.  In  other 
words,  when  executing  a  status  check,  the 
instruction  JZ  (jump  if  zero)  should  have 
been  JNZ  (jump  if  not  zero).  I  know  the 
MIO  card  is  working  properly  and  wired 
per  the  manufacturer’s  specifications  be¬ 
cause  the  firmware  monitor  in  a  factory 
ROM  controls  the  MIO  card  without  a 
hitch.  Now  it  should  be  noted  that  IMSAI 
has  been  out  of  business  for  several  years 
and  expecting  a  vendor  to  support  equip¬ 
ment  which  is  no  longer  supported  by 
even  the  manufacturer  could  be  asking 
too  much. 

The  package  my  company  ordered 
for  a  brand-new  Molecular  Super  Micro 
30  had  two  fatal  bugs.  Molecular’s  N/Star 
operating  system  uses  an  expanded  and 
larger-than-normal  CCP.  Fortunately,  this 
package  was  purchased  as  assembly  lan¬ 
guage  source  code.  I  had  no  trouble  track¬ 
ing  down  three  places  in  the  source  code 
that  expected  the  normal  sized  CCP  and 
making  the  proper  modifications.  The 
second  error  surfaced  when  the  “phone  is 
ringing”  response  from  the  smart  modem 
caused  the  activity  time-out  timer  to 
reset.  This  was  fixed  by  telling  the  smart 
modem  not  to  send  responses  after  a 
caller  connected. 

COMMX-PAC  includes,  in  addition 
to  COMMX  and  CONSOLX  (discussed  be¬ 
low),  a  “data  base  management”  program 
and  a  message  board  program  both  writ¬ 
ten  in  Hawkeye  Grafix  compiled  VBASIC. 
Neither  of  these  programs  performs  as  well 
as  the  public  domain  programs  available 
on  larger  RCPM  systems  and  through 
user’s  groups. 

COMMX-PAC  is  two  separate  pack¬ 
ages:  COMMX  for  connecting  to  a  host 
computer  like  the  Source  or  an  RCP/M 
and  CONSOLX  for  making  your  computer 
act  like  a  host  or  RCP/M. 


COMMX 

COMMX  is  the  terminal  program  that 
allows  your  computer  to  communicate 
with  other  (host)  computers.  COMMX  is 
far  superior  to  even  the  most  advanced 
public  domain  MODEM  program  that  I 
have  seen  to  date.  It  can  virtually  com¬ 
municate  with  any  system  like  IBM  TSO, 
HP-3000,  as  well  as  RCP/M’s.  It  has  key¬ 
board  macro  definitions;  an  entire  call, 
connect,  and  log-on  procedure  can  be 
compressed  to  one  or  two  keystrokes.  A 
half-dozen  separate  programs  allow  for 
an  automatic  dial-up  directory,  encoding 
and  decoding  private  files  and  un-loading 
binary  files  to  INTEL  HEX  format  files 
for  systems  that  are  restricted  to  sending 
and  receiving  only  seven  bits  of  data. 

Hawkeye  has  included  Dick  Green¬ 
law’s  squeeze  and  un-squeeze  programs 
among  its  utilities.  These  can  cut  modem 
connect  time  by  50%  by  compacting  the 
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file  to  be  sent,  sending  the  compacted 
version  and  then  un-compacting  it  at  the 
receiving  end.  There  is  also  a  sorted  disk 
directory  utility  but  this  utility  is  not  as 
impressive  as  the  public  domain  program 
SD-44.COM  (Super  Directory)  described 
in  The  CP/M  Exchange  column  of  DDJ, 
June  1983. 

COMMX  supports  two  error-checking 
protocols  and  two  methods  of  file  trans¬ 
fer.  The  COMMX- to-COMMX  file  transfer 
system  seems  to  be  more  advanced  than 
the  COMMX-to-MODEM7  system.  Earlier 
versions  of  COMMX  didn’t  support  the 
Christensen  protocol  and  I’m  glad  to  see 
the  newer  version  does. 

The  most  advanced  feature  of 
COMMX  is  the  E-MAIL  feature.  Using 
the  dial-up  directory,  keyboard  macros, 
and  a  submit  file,  COMMX  can  establish 
communication  with  other  COMMX/ 
CONSOLX  sites  and  exchange  mail  files 
while  each  site  is  unattended.  The  entire 
process  can  be  initiated  and  then  delayed 
a  specified  number  of  hours  and  minutes 
to  take  advantage  of  off-hour  phone 
charges.  COMMX  continues  trying  to 
establish  communications  until  the  job  is 
completed.  This  E-MAIL  requires  the 
most  effort  to  get  operational,  but  the 
manual  is  clear  and  well  laid  out  in  de¬ 
scribing  the  E-MAIL  features. 

The  manual  also  includes  an  index 
and  even  a  glossary  for  non-computing 
types  to  refer  to.  Eighty  percent  of  the 
manual  is  dedicated  to  COMMX  with  the 
remaining  twenty  percent  devoted  to 
CONSOLX. 


CONSOLX 

CONSOLX,  like  COMMX,  is  con¬ 
figured  at  the  factory  to  the  user’s  ma¬ 
chine  and  modem.  The  list  of  supported 
machines  and  modems  is  long  and  grow¬ 
ing.  I  guess  nine  of  ten  personal  as  well  as 
business  micros  are  currently  supported. 

CONSOLX  allows  your  computer  to 
function  as  a  host  to  callers  accessing 
your  system.  Field  selectable  options 
include  a  password,  ring-back  operation, 
a  welcome  message,  and  UART  configura¬ 
tion  to  either  7-bit  even  parity  or  8 -bit 
no  parity.  An  auto  start  feature  allows 
your  system  to  execute  a  program  after 
the  user  gets  past  the  optional  password 
and  welcome  message. 

At  the  Money  Tree  (the  company  I 
work  for)  we  run  a  system  that  logs  call¬ 
ers  in,  gives  them  access  to  proprietary 
financial  information,  and  logs  them  off, 
keeping  track  of  time  and  charges.  Be¬ 
cause  of  its  ability  to  answer  the  phone 
and  then  autoload  and  execute  other  pro¬ 
grams,  CONSOLX  works  well  as  the  base 
system.  Callers  see  only  as  much  of  the 
system  as  they  need  to  see.  I  know  of  at 
least  one  other  business  using  CONSOLX 
commercially. 


Conclusion 

I  had  to  write  the  routines  to  switch 
baud  rates  in  the  CONSOLX  program  and 
I  think  these  should  be  included  in  the 
package.  Also,  working  without  carrier 
detect  requires  disorderly  log-offs  to  time 
out  for  five  minutes  before  the  next  caller 
can  connect.  I  was  able  to  get  around  this 
on  the  Molecular,  but  I’m  not  sure  this 
problem  can  be  solved  generally  for  all 
systems. 

For  some  of  us,  getting  a  program  to 
work  is  half  the  fun  of  computing.  For 
others  who  want  it  to  work  the  first  time 
and  every  time,  COMMX-PAC  from 
Hawkeye  Grafix  is  clearly  worth  the  $150 
price  tag.  Furthermore,  if  you  have  no 
need  for  making  your  computer  a  host 
computer  and  only  want  to  originate  calls 
to  other  host  systems,  the  COMMX  pro¬ 
gram  alone  sells  for  $99. 

I  commend  Hawkeye  Grafix  for  an 
outstanding  package  in  COMMX-PAC. 
They  have  taken  on  a  tough  job  of  pro¬ 
viding  software  for  various  hardware 
environments,  and  as  far  as  I  know  they 
are  doing  the  job  well.  My  calls  to  Will 
Pierce  have  always  been  given  professional 
yet  personal  treatment.  I  can  personally 
recommend  all  their  fine  products,  espe¬ 
cially  the  COMMX-PAC  communications 
package. 

■■J 


Dr.  Dobb’s  Journal,  December  1983 

790 


115 


BOOK  REVIEWS 


An  Introduction  to  Programming 
and  Problem  Solving  with  Pascal, 
Second  Edition 
By  G.  Michael  Schneider,  Steven  W. 

Weingart,  and  David  Perlman 
Published  by  John  Wiley  &  Sons,  Inc. 
$21.95,  468  pages 

Reviewed  by  William  G.  Hutchison,  Jr. 

“What?  Another  Pascal  textbook?” 
If  your  reaction  was  the  same  as  this  re¬ 
viewer’s,  please  do  not  give  up  in  despair. 
This  book  is  not  another  quick-and-dirty 
attempt  to  cash  in  on  the  demand  for 
computer  texts;  it  is  a  thoroughly  profes¬ 
sional  effort.  It  comes  from  that  hotbed 
of  Pascal  activity,  the  University  of  Min¬ 
nesota.  Andy  Mickel  read  the  proof  copy. 
You  may  remember  him  as  the  former 
editor  of  Pascal  News.  Niklaus  Wirth  was 
interested  enough  in  the  project  to  write 
a  foreword. 

This  is  clearly  a  college  text.  The 
authors  wrote  it  to  be  used  as  text  for  the 
course  CS  I,  Computer  Programming  I,  of 
ACM  Curriculum  ’78.  They  have  achieved 
a  very  good  balance  of  subject  material. 
Some  authors  overload  their  readers  with 
thorny  calculus  problems  to  be  pro¬ 
grammed.  This  is  useful  material,  but  not 
suitable  for  an  introductory  programming 
course.  This  text  is  evenly  balanced  be¬ 
tween  text  processing  applications,  com¬ 
mercial  (payroll  and  inventory),  games 
(LIFE),  and  elementary  statistics.  The 
authors  use  real  programs  as  examples, 
not  meaningless  fragments  cooked  up  just 
to  display  some  feature  of  the  language. 

The  authors  follow  their  own  advice, 
which  is  to  plan  what  to  do  before  begin¬ 
ning  the  coding.  Chapter  1  is  devoted  to 
problem  specification.  They  point  out 
correctly  that  most  program  errors  start 
from  errors  or  ambiguities  in  the  state¬ 
ment  of  the  problem,  so  it  is  worthwhile 
to  spend  considerable  time  getting  it  right 
at  the  beginning.  Chapter  2  is  about 
developing  algorithms  in  pseudo-code.  It 
contains  a  brief  discussion  of  program 
efficiency  and  asymptotic  analysis  (e.g., 
big-O  function,  rc-squared  versus  n  log  n 
performance),  not  enough  to  bog  down 
the  reader,  but  enough  to  stimulate  the 
student  to  take  the  next  course. 

In  addition  to  the  usual  programming 
material,  this  book  includes  a  chapter  on 
modular  program  design,  and  one  on  pro¬ 
gram  debugging,  testing,  documentation, 
and  maintenance.  Unlike  some  authors, 
they  do  not  succumb  to  the  illusion  that 
structured  programming  means  no  errors 


in  programs!  That  is  what  makes  this 
book  more  than  just  another  textbook. 
The  technical  material  is  well  organized 
and  presented,  and  it  also  contains  a  great 
deal  of  practical  wisdom,  which  will  save 
the  careful  reader  from  many  unnecessary 
mistakes. 

The  Pascal  language  used  here  is  that 
of  the  Jensen  &  Wirth  text,  PASCAL  Users 
Manual  and  Report,  Springer-Verlag,  1974. 
It  is  presented  in  syntax  graphs  inline  in 
the  text  as  needed,  and  complete  in  an 
appendix.  The  timing  of  the  text  may  be 
unfortunate.  It  is  a  rewrite  of  a  1978  edi¬ 
tion.  At  that  time,  there  was  no  official 
standard  for  Pascal,  so  it  contains  no  ref¬ 
erence  to  ISO  standards  or  to  conformant 
array  parameters.  That  is  not  a  serious 
problem  for  an  introductory  text,  because 
the  core  of  the  language  is  almost  un¬ 
changed  since  1978.  There  is  practically 
no  reference  to  UCSD  Pascal  or  other 
non-standard  versions.  There  is  a  brief 
discussion  of  versions  with  INTERAC¬ 
TIVE  files  (which  do  not  do  a  GET  first 
in  READ),  and  a  note  about  versions 
with  direct  access  files. 

The  only  thing  missing  from  this  ex¬ 
cellent  text  is  a  discussion  of  quicksort, 
which  other  authors  have  managed  to 
present  in  an  elementary  manner.  Let’s 
not  produce  another  generation  of  pro¬ 
grammers  who  know  only  bubble  sort ! 


Language  Translations 
By  John  Zarrella 
Published  by  Microcomputer 

Applications,  Inc. 

$14.95,  200  pages 
Reviewed  by  Michael  Carter 

Not  the  least  of  the  advantages  of  the 
microcomputer  revolution  is  the  encour¬ 
agement  and  indeed  the  incentive  it  gives 
the  owner  of  a  personal  computer  to 
delve  into  its  workings  and  operations. 
This  will  inevitably  lead  to  the  spread  of 
computer  know-how  from  a  select  few  to 
a  wider  audience  —  a  development  which 
I  for  one  heartily  applaud.  It  also  implies 
the  existence  of  a  market  for  introduc¬ 
tory  computer  texts,  of  which  this  book 
is  a  good  example.  The  author  of  such  a 
book  faces  a  considerable  problem  —  how 
to  aim  at  an  easy  presentation  without 
oversimplification.  The  current  author  is 
partially  —  but  only  partially  —  successful. 

No  user  of  a  personal  computer  can 
avoid  forming  an  intimate  acquaintance 
with  at  least  one  language  translator  (most 


commonly  BASIC).  A  language  translator 
is  a  computer  program  which  accepts  a 
human-oriented  source  language  as  input, 
translating  it  into  a  form  which  can  be 
directly  executed  by  the  computer.  It  is 
the  medium  through  which  the  user  con¬ 
veys  his  or  her  wishes  to  the  machine. 

After  a  general  introduction,  Zarrella 
deals  in  turn  with  the  three  main  types  of 
language  translator:  assemblers,  interpre¬ 
ters  (e.g.,  APL,  BASIC,  Forth),  and  com¬ 
pilers  (e.g.,  C,  COBOL,  Pascal,  Fortran). 
He  appropriately  emphasizes  two  impor¬ 
tant  points.  First,  interpreters  and  com¬ 
pilers  are  not  distinct  categories  but 
rather  the  ends  of  a  continuum  with  most 
language  translators  lying  somewhere  in- 
between.  The  reader  will  thus  understand 
why  a  BASIC  program  is  stored  in  the 
machine  in  a  form  which  he  or  she  cannot 
readily  read.  The  second  important  point 
is  that  the  basic  tasks  required  of  a  lan¬ 
guage  translator  are  the  same  whether  it  is 
an  assembler,  compiler,  or  interpreter. 
Consequently,  assemblers,  compilers,  and 
interpreters  are  made  up  of  essentially  the 
same  functional  components. 

Zarrella  makes  convenient  use  of  the 
latter  point  in  the  second  half  of  the 
book  when  he  deals  in  successive  chapters 
with  the  functional  components  of  any 
language  translator:  lexical  analysis,  syn¬ 
tax  analysis,  semantic  analysis,  code 
generation,  and  optimization.  The  lexical 
analyser  examines  the  source  text  and 
divides  it  into  its  component  parts:  sym¬ 
bols,  numbers,  punctuation,  and  so  on. 
The  syntax  analyser  parses  the  input 
program  to  verify  that  it  is  a  valid  pro¬ 
gram  in  the  language  and  to  provide  an 
appropriate  framework  for  the  next  step. 
This  is  semantic  analysis  which  deter¬ 
mines  the  meaning  of  the  source  program. 
Code  generation  produces  the  actual  exe¬ 
cutable  machine  code.  Finally,  optimiza¬ 
tion  makes  minor  changes  in  the  executa¬ 
ble  machine  code  to  increase  execution 
speed  and/or  decrease  storage  require¬ 
ments.  It  should  not  be  concluded  that 
these  five  components  of  a  language 
translator  can  necessarily  be  distinguished 
as  separate  entities  that  follow  one  anoth¬ 
er  in  the  order  given.  They  are  conceptual 
divisions,  and  with  the  exception  of  opti¬ 
mization,  they  must  be  provided  for  in 
every  language  translator.  The  five  con¬ 
stituent  parts  provide  an  appropriate 
framework  for  approaching  the  general 
task  of  language  translation. 

The  five  chapters  dealing  with  the 
constituent  parts  of  a  language  translator 
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are  preceded  by  a  chapter  on  “Languages 
and  Grammars.”  This  is  the  theoretical 
core  on  which  language  translation,  in 
particular  syntax  analysis,  is  based. 
Unfortunately,  this  is  not  easy  material 
to  grasp  and  the  chapter  will  probably  re¬ 
quire  more  than  one  reading.  It  is  here 
and  in  the  chapter  dealing  with  syntax 
analysis  that  Zarrella’s  exposition  falters. 
I  think  this  is  because  he  is  trying  to  com¬ 
press  some  complex  ideas  into  two  short 
chapters.  Unfortunately,  this  material  is 
really  the  core  of  the  matter  and  it  left 
me  feeling  unsatisfied.  I  think  some  more 
material  would  have  been  justified.  Furth¬ 
er,  I  found  his  use  of  the  analogy  of  a 
divisionalized  company  to  explain  top- 
down  parsing  overdone  and  superfluous. 

There  are  three  supplementary  chap¬ 
ters  which  have  not  yet  been  mentioned. 
One  deals  with  program  development  util¬ 
ities:  linkers,  loaders,  library  managers, 
etc.  A  second  deals  with  macros,  which 
are  most  commonly  (but  not  exclusively) 
found  in  conjunction  with  assemblers.  A 
third  deals  with  the  important  topic  of 
error  processing.  A  glossary,  a  short 
bibliography,  and  an  index  round  out  the 
book. 

This  book  has  an  admirable  objective: 
to  present  the  general  concepts  of  language 
translation,  emphasizing  the  similarities 
between  the  different  classes  of  assembler, 
interpreter,  and  compiler  in  a  manner 
accessible  to  the  neophyte.  This  is  a  very 
ambitious  task  and  one  in  which  the 
author  is  not  entirely  successful.  I  suspect 
that  it  is  more  likely  to  whet  the  appetite 
than  satisfy  it.  Hopefully,  it  will  encourage 
the  reader  to  seek  further  information  in 
one  of  the  more  substantial  texts.  To  any 
computer  user  who  is  curious  about  what 
lies  behind  the  cosy  facade  of  a  BASIC 
interpreter  or  wonders  why  Pascal  can’t 
be  like  BASIC,  I  suggest  this  book  as  a 
good  place  to  start. 

Z80  Assembly  Language 

Subroutines 

By  Lance  A.  Leventhal  and 

Winthrop  Saville 

Published  by  Osborne/McGraw-Hill 
$15.95,  498  pages,  paperback 
Reviewed  by  Paul  J.  Gans 

Learning  assembly  language  for  a 
new  computer  is  not  easy  for  anyone. 
Even  experienced  programmers  go  through 
a  period  of  adjustment  when  faced  with  a 
new  machine.  Novices  are  urged  to  study 
the  architecture  of  the  new  machine  to 
learn  its  op  codes  and  addressing  modes 
and  to  struggle  as  best  they  can  to  write 
simple  routines  that  have  been  written 
countless  times  before. 

More  experienced  programmers  know 
that  there  is  more  to  it  than  that.  They 
do  not  become  comfortable  in  the  ma¬ 
chine  language  of  a  new  machine  until 


they  have  mastered  its  idioms.  Z8G  Assem¬ 
bly  Language  Subroutines  is  a  book  of 
idioms  for  the  Z80.  It  is  a  wonderful 
book  that  can  be  read  with  profit  by  any¬ 
one  not  yet  able  to  speak  idiomatic  Z80. 

The  book  begins  with  an  explanation 
of  Z80  architecture  (with  a  section  for 
experienced  programmers,  pointing  out 
distinguishing  features  and  difficulties 
with  the  Z80)  and  theZ80  instruction  set. 
The  instruction  set  is  presented  from  a 
programmer’s  point  of  view.  Thus  instruc¬ 
tions  are  grouped  according  to  function. 
For  instance,  under  “Storing  Registers  in 
Memory”  follow  direct  storage  of  regis¬ 
ters,  indirect  storage  of  registers,  indexed 
storage  of  registers,  etc.  The  instruction 
set  is  covered  fully  with  many  examples. 

Chapter  2,  entitled  “Implementing 
Additional  Instructions  and  Addressing 
Modes,”  is  filled  with  instances  of  com¬ 
mon  operations  requiring  more  than  a 
single  instruction.  These  operations  occur 
repeatedly  in  real  programming.  The 
novice  must,  each  time,  figure  out  how 
best  to  perform  them.  These  operations 
are,  in  fact,  idioms,  and  are  at  the  finger¬ 
tips  of  experienced  programmers.  For 
example,  how  does  one  compare  the  con¬ 
tents  of  the  HL  register  pair  to  a  16-bit 
immediate  value?  On  page  81,  Leventhal 
and  Saville  give  two  methods,  one  requir¬ 
ing  two  instructions,  the  other,  three. 
Chapter  3  is  devoted  to  common  pro¬ 
gramming  errors  and  includes  such  topics 
as  using  the  flags  incorrectly,  confusing 
registers  and  register  pairs,  and  handling 
arrays  incorrectly. 

The  bulk  of  the  book,  however,  is 
devoted  to  assembly  language  subroutines. 
There  are  more  than  50  of  them,  covering 
topics  such  as  code  conversion  ( binary  to 
BCD,  ASCII  decimal  to  binary,  EBCDIC 
to  ASCII,  etc.),  array  manipulation,  arith¬ 
metic  (multiple-precision  binary  division, 
etc.),  string  manipulation  (compare,  con¬ 
catenate,  etc.),  array  operations,  input/ 
output,  and  interrupts.  Each  subroutine 
listing  is  elaborately  commented,  entry 
and  exit  conditions  are  clearly  given,  and 
execution  times  (in  machine  cycles)  are 
provided.  There  is  an  introductory  expla¬ 
nation  of  the  function  of  each  subroutine 
and  a  description  of  how  it  works.  Best  of 
all,  test  data  and  results  are  given.  Much 
can  be  learned  by  examination  of  these 
subroutines,  and,  better  yet,  they  are 
useful. 

The  Z80  instruction  mnemonics  used 
are  Zilog’s,  which  I  believe  are  superior  to 
the  multiple  and  incompatible  sets  of 
pseudo-8080  mnemonics  in  common  use. 
All  notational  conventions  are  explained. 
Appendices  contain  a  detailed  Z80  in¬ 
struction  set  summary  with  reproductions 
of  the  Zilog  instruction  charts,  a  program¬ 
ming  reference  to  the  Z80  PIO,  and  an 
ASCII  character  set  chart.  The  book 
concludes  with  a  23 -page  glossary  and  a 
useful  index. 


Mathematical  Theories  of  Optimi¬ 
zation;  Proceedings,  S.  Margherita 
Ligure  1981;  Lecture  Notes  in 
Mathematics  Series  No.  979 
Edited  by  A.  Dold  and  B.  Eckmann 
Published  by  Springer-Verlag 
$14.50,  268  pages,  paperback 
Reviewed  by  Robert  Irving 


Optimization  is  the  science  of  obtain¬ 
ing  the  maximum  return  for  investment 
of  resources  under  a  given  set  of  condi¬ 
tions.  The  field  is  also  known  as  “opera¬ 
tions  research”  from  its  initial  application 
in  World  War  II.  The  most  common  appli¬ 
cations  lie  in  the  areas  of  inventory  con¬ 
trol,  product  selection,  and  manufactur¬ 
ing  scheduling. 

Engineers  and  computer  scientists  in 
the  field  of  optimization  are  usually  look¬ 
ing  for  applied  solutions  to  real  problems. 
They  generally  want  either  an  algorithm 
or  a  program  which  will  solve  the  problem 
at  issue.  Mathematicians,  on  the  other 
hand,  are  not  necessarily  looking  for  solu¬ 
tions  as  such.  They  are  more  interested  in 
the  nature  of  the  statement  of  the  prob¬ 
lem.  Such  things  as  “existence  theorems” 
(does  a  solution  exist?)  and  “robustness” 
(does  the  solution  apply  over  a  broad 
range  of  conditions?)  are  of  more  import 
than  a  particular  solution. 

This  book  is  pure  mathematics  with 
potential  practical  application.  Conse¬ 
quently,  it  is  of  little  direct  interest  to 
most  computer  programmers. 

Ultimately,  some  of  the  articles  may 
lead  to  algorithms  of  great  importance. 
For  example,  the  article  by  L.  Cesari  on 
“Existence  of  Solutions  and  Existence  of 
Optimal  Solutions”  may  someday  en¬ 
courage  other  mathematicians  to  produce 
algorithms  with  which  we  can  optimize 
some  problems  not  now  covered,  but 
possible. 

On  the  other  hand,  I  see  little  to 
no  potential  use  for  a  discussion  by  A. 
Bensoussan  on  page  71,  entitled  “On  the 
Production  Smoothing  Problem,”  in  which 
he  extends  a  discrete  case  to  a  continuous 
case.  First,  I  know  of  no  “continuous” 
production  process.  Even  oil  refineries, 
which  work  with  large  volumes  of  material, 
operate  on  a  “batch”  basis.  No  two 
batches  have  the  same  characteristics, 
hence  the  run  will  be  “continuous”  only 
for  the  length  of  the  batch.  Second,  all  of 
us  who  make  mathematical  models  on  the 
computer  know  that  we  are  dealing  with 
discrete  processes,  since  that  is  the  only 
kind  of  process  the  computer  can  deal 
with. 

Unless  you  are  a  “pure”  mathema¬ 
tician  interested  in  the  rigors  of  that  field, 

I  suggest  you  forgo  buying  this  volume. 
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Teletext  and  Videotex 

in  the  United  States 

By  John  Tydeman,  Hubert  Lipinski, 

Richard  P.  Adler,  Michael  Nyhan, 

and  Laurence  Zwimpfer 
Published  by  McGraw-Hill 
$30.00,  314  pages 
Reviewed  by  Susan  Bowers 

Teletext  (one-way  information  ser¬ 
vices)  and  Videotex  (two-way  information 
services)  are  new  technologies  created  by 
the  marriage  of  computing  and  communi¬ 
cations.  They  emerged  in  England  and 
France  in  the  1970’s,  have  been  growing 
rapidly  in  Europe,  Canada,  and  Japan, 
and  are  currently  becoming  important 
tools  in  this  country. 

Teletext  and  Vidotex  in  the  United 
States  is  a  look  at  Teletex  and  Videotex 
from  a  futurist  viewpoint.  Using  careful 
research  and  documentation,  this  in-depth 
overview  deals  with  three  classes  of  ser¬ 
vices:  public  data  bases,  closed  user  groups, 
and  private  systems.  Full  of  charts  and 
tables,  the  book  looks  at  the  present  and 
future  states  of  this  technology  in  the 
United  States.  The  first  five  chapters  deal 
with  defining  the  phenomenon,  detailing 
its  history,  assessing  the  current  state  of 
information  services,  and  discussing  possi¬ 
ble  future  applications.  The  rest  of  the 
book  develops  a  model  which  studies  the 
possible  extent  and  impact  of  Teletext 
and  Videotex  in  the  United  States  by  the 
end  of  this  century. 

The  book  emphasizes  such  public  pol¬ 
icy  concerns  as  the  effect  of  those  tech¬ 
nologies  on  society,  legal  aspects,  security, 
privacy,  standards,  consumer  protection, 
international  ramifications,  advertising 
liability,  and  impartiality.  The  modeling 
and  forecasting  are  organized  and  care¬ 
fully  done,  covering  the  possible  futures 
from  several  perspectives.  There  is  an  im¬ 
pressive  appendix  on  policy  issues  and  an 
extensive  bibliography,  as  well  as  a  com¬ 
prehensive  index. 

Teletext  and  Videotex  in  the  United 
States  provides  an  interesting  look  at 
future  trends  in  the  information  services. 
Several  parts  of  it  would  add  much  to  a 
study  of  computers  in  society;  it  could 
also  be  an  excellent  textbook  for  a  course 
on  the  future  impact  and  direction  of 
information  services  in  the  United  States. 
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OF  INTEREST 


by  Michael  Wiesenberg 


Stop  Noise 

Kalglo’s  IPC  international  model 
computer  power  control  console  with 
surge  suppression  and  power  line  noise 
filter  has  six  individually  switched 
IEC-320/CEE-22  outlets  in  dual 
separately  filtered  banks  of  three  each. 
It  absorbs  318  joules  at  18,200  amp 
pulse,  is  rated  at  10  amps  maximum 
with  100  or  260  VAC  operation,  50  or 
60  Hz,  weighs  2.5  pounds,  and  costs 
$150.  Reader  Service  No.  101. 

The  Lemon  AC  Surge  Protector 
from  Electronic  Protection  Devices 
gives  protection  in  excess  of  6000 
volts  and  200  amps,  with  instantaneous 
voltage  clamping  including  grounding 
to  prevent  flashover  to  other  ports  and 
damage  to  equipment.  The  company 
thinks  its  product  is  so  good  that 
insurance  by  Lloyd’s  of  London  is  in¬ 
cluded,  protecting  user  hardware  up  to 
$2500  from  damage  caused  by  transi¬ 
ent  voltage  surges.  The  Lemon  lists  for 
$59.95.  Reader  Service  No.  103. 


Buffer  It 

Big- Buffer  from  Mikrocomputer- 
technik  of  Germany  is  a  Centronics- 
compatible  hardware  spooler  for  paral¬ 
lel  printers.  The  8K  version  is  $170, 
the  32K  version  is  $195,  the  64K  is 
$256,  the  96K  is  $317,  and  the  120K 
is  $363.  You  get  all  cables  and  connec¬ 
tors  (36 -pin  Centronics  with  female 
input  and  male  output).  Power  comes 
from  the  printer  using  pin  18  of  the 
Centronics  connector,  or  you  can  pur¬ 
chase  a  separate  110V,  60Hz  power 
supply  for  $30.  These  prices  are  based 
on  the  exchange  rate  at  the  time  of  the 
release,  2.60  DM  to  $  1  US,  and  are  sub¬ 
ject  to  change.  Reader  Service  No.  105. 


Can't  Rip  It 

Micro  Format  has  FlexiDisk  Enve¬ 
lopes  made  of  Dupont’s  Tyvek,  a  sup¬ 
posedly  tear-  and  wear-proof  substance 
that  looks  and  feels  like  paper.  They 
included  a  sample  with  their  press 
release,  and  I  couldn’t  tear  the  stuff. 
Each  package  has  25  envelopes,  and 
you  get  five  packages  postpaid  for  $25. 
Reader  Service  No.  107. 


TRS-80  Assembly  Language 
Programming 

TRS-80/Z80  Assembly  Language 
Library  by  Craig  Lindley  from  WG- 
Books  has  75  program  listings  to  thor¬ 
oughly  explain  assembly  language  on 
the  TRS-80,  and  includes  twoTRSDOS 
disks  with  33  source  and  object  files, 
for  $34.97.  Reader  Service  No.  109. 


Dr.  Dobb,  Meet  Dr.  Logo 

Dr.  Logo,  from  Digital  Research, 
is  an  advanced  version  of  Logo  for  16- 
bit  micros,  in  particular  the  IBM  PC 
and  XT.  It  uses  turtle  graphics,  just 
like  the  popular  version  of  the  lan¬ 
guage.  Written  in  C,  Dr.  Logo  is  trans¬ 
ferable  to  other  systems.  You  get  a  larg¬ 
er  work  space,  with  over  10,000  nodes 
of  memory,  built-in  help  commands, 
a  full-screen  procedure  editor  (with 
on-line  help  as  well).  Also  supported  are 
comments,  indentation,  user-defined 
words,  windowing,  upper  and  lower 
case,  new  primitives,  string  processing, 
line  editing,  and  debugging  with  a  trace 
mode  and  a  watch  mode.  The  latter  is 
for  checking  or  modifying  variables  or 
expressions  immediately  after  execu¬ 
tion  of  a  statement.  Cross  referencing, 
double-precision  floating  point,  tran¬ 
scendental  functions,  and  a  $149.95 
price  tag  are  part  of  the  package  as 
well.  Reader  Service  No.  111. 


Go  Forth  on  PC 

HSFORTH,  from  Harvard  Soft- 
works,  is  Forth-79  for  the  PC  and 
other  8086  and  8088  machines.  Word 
names,  definition  lists,  and  machine 
codes  use  separate  segments,  permit¬ 
ting  programs  up  to  192K.  HSForth 
runs  the  Sieve  of  Eratosthenes  in  47 
seconds,  as  opposed  to  70  to  140 
on  other  Forths,  and  2000  for  inter¬ 
preted  BASIC.  Auto-Opt  and  the  Micro- 
Asm  extension  reduce  the  time  to  five 
seconds.  Even  optimized  machine 
code,  according  to  Harvard  Softworks, 
runs  no  faster  than  five  seconds.  $220. 
Reader  Service  No.  113. 


Things  I've  Tried 

Usually  the  products  I  write  about 
in  this  column  are  picked  from  a  stack 
of  press  releases  sent  each  month  to 
DDJ.  I  rarely  have  the  product  in  front 
of  me  when  writing  about  it,  and  de¬ 
scriptions  here  are  not  intended  to  be 
endorsements. 

Once  in  a  while  I  do  get  the  oppor¬ 
tunity  to  try  out  products,  and  I’d  like 
to  share  a  few  with  you. 

You  may  have  gathered  from  pre¬ 
vious  columns  that  I  like  inexpensive 
computers,  particularly  the  Timex 
products.  One  of  the  wonderful  things 
you  can  do  with  a  TS1000  or  1500  is 
learn  Z80  assembly  language.  BASIC 
on  a  Timex  runs  achingly  slow,  partic¬ 
ularly  since  some  60%  of  the  micro¬ 
processor’s  time  is  spent  updating  the 
screen.  Machine  code  programs,  how¬ 
ever,  run  literally  hundreds  of  times  as 
fast  as  BASIC  ones.  Several  good 
books  have  been  written  about  machine 
code  programming  on  the  TS1000. 
The  best  of  these  are  two  by  Dr.  Ian 
Logan,  whose  knowledge  of  the  ZX80 
and  81  (predecessors  of  the  TS1000) 
is  exceeded  only  by  that  of  Clive  Sin¬ 
clair  (inventor  of  these  and  the  Spec¬ 
trum,  a  version  of  which  should  now 
be  available,  modified  by  Timex  and 
called  the  2068). 

You  cannot  write  effective  code 
for  these  little  wonders  without  know¬ 
ing  the  entry  points  for  the  various 
system  variables.  Melbourne  House,  an 
international  publishing  company,  has 
Dr.  Logan’s  Understanding  Your  ZX81 
ROM,  $14.95,  and  The  Complete 
TS 1000 / Sinclair  ZX81  ROM  Disassem¬ 
bly,  $  1 9.95 ,  and  their  own  apparently 
authorless  Machine  Language  Program¬ 
ming  Made  Simple  for  Your  Sinclair  & 
Timex  TS1000,  $14.95.  I  have  all  three 
of  these,  and  they  are  excellent.  Mel¬ 
bourne  also  offers  Not  Only  30  Pro¬ 
grams  for  the  Sinclair  ZX81,  $9.95, 
program  listings  that  ingeniously  all 
run  in  the  “unexpanded”  TS1000  (2K 
RAM),  and  what  appears  to  be  the 
ultimate  hardware  manual  for  the  two 
“simpler”  machines.  The  Ins  and  Outs 
of  the  Timex  TS1000  &  ZX81,  by  Don 
Thomasson,  $  12.95.  Add  $2  for  p.&h., 
and  residents  of  California,  Maryland, 
and  Tennessee  add  sales  tax.  Melbourne 
carries  software  and  books  for  Timex, 
TRS80,  Vic  20,  and  Commodore  64. 
They  will  send  you  a  free  catalog  and 
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are  looking  for  contributions  from 
authors.  Reader  Service  No.  115. 

Far  better  than  hand-assembling 
your  machine  code  programs  and  then 
trying  to  POKE  them  into  various 
memory  locations  is  to  use  an  assem¬ 
bler.  International  Publishing  &  Soft¬ 
ware  Inc.  offers  ZX  Assembler.  It  has 
its  own  editor.  You  write  programs 
using  standard  Z80  mnemonics.  No 
need  to  figure  jump  addresses;  just  use 
labels  and  the  assembler  figures  them 
for  you.  Programs  assemble  in  seconds 
and  execute  either  directly  from  ZX 
Assembler’s  monitor  mode  or  from  a 
program  that  executes  with  a  USR 
statement  where  the  code  is  in  a  REM 
statement  created  by  the  assembler. 
The  assembler  also  retains  the  source 
code  in  a  second  REM  statement. 

You  can  SAVE  the  entire  program 
on  tape,  and  alter,  modify,  and  reassem¬ 
ble  it.  Those  familiar  with  machine  code 
on  the  TS  will  appreciate  this  method, 
because  code  loaded  in  other  areas  is 
either  difficult  to  save  or  cannot  use 
relative  addressing.  In  the  monitor 
mode  you  can  move  whole  blocks  of 
code  from  one  memory  location  to 
another,  examine  and  modify  any  loca¬ 
tion  of  RAM,  inspect  and  modify  regis¬ 
ters,  and  search  the  entire  memory  for 
any  byte  sequence.  ZX  Assembler  costs 
$14.95.  International  Publishing  pro¬ 
vides  a  free  catalog  and  the  name  of 
the  nearest  dealer  that  handles  this  and 
other  useful  products,  including  ZX 
Bug,  $14.95,  for  debugging,  editing, 
and  running  machine  codes.  Toolkit, 
$14.95,  to  add  nine  powerful  com¬ 
mands,  including  a  renumber  that 
changes  all  GOTO  and  GOSUB  refer¬ 
ences,  Fastload,  $19.95,  to  load  any 
program  four  to  six  times  as  fast,  ZX 
Forth,  $29.95,  for  the  ease  of  BASIC 
with  machine  code  speed,  and  a  stack 
of  clever  games.  Reader  Service  No.  117. 

If  I  knew  that  a  product  did  not 
live  up  to  its  claims,  I  would  not  list  it 
here.  Usually  I  have  no  way  of  knowing 
that,  because  I  just  go  by  the  press  re¬ 
leases,  which,  naturally,  are  never  unfa¬ 
vorable.  Such  was  the  case  with  Memo- 
tech,  whose  various  memory  modules 
and  auxiliary  keyboard  for  the  TS  1000 
I  cited  a  few  months  back.  I  believed 
their  hype  myself  and  shortly  after¬ 
ward  bought  their  keyboard  and  32K 
memory  for  my  system.  That  first  32K 
memory  didn’t  work  at  all,  and  I  took 
it  back  to  the  store.  The  replacement 
32K  refused  to  work  in  conjunction 
with  either  Memotech’s  keyboard  or 
the  Timex  printer.  This  was  not  much 
use  to  me  since  I  needed  the  printer 
for  listings  during  program  develop¬ 
ment.  I  took  my  entire  system  to  the 
store,  and  they  could  get  the  32K 
memory  and  auxiliary  keyboard  to 
work  with  their  systems  only  separate¬ 


ly,  not  together. 

I  called  Memotech  several  times 
for  help,  and  they  kept  insisting  that 
they  had  tested  a  setup  identical  to 
mine  with  no  problems.  Finally  they 
agreed  to  look  at  my  system  if  I  would 
send  it  to  them  and,  if  either  of  their 
products  was  defective,  to  replace  or 
fix  it.  I  called  them  when  the  system 
was  in  their  hands,  and  the  technician 
to  whom  I  spoke  said  he  had  set  up 
my  system  and  it  had  been  running 
perfectly  for  ten  minutes,  and  he 
could  find  nothing  wrong  with  it.  But 
while  I  was  on  the  phone  with  him  he 
said,  “Wait  a  minute.  It’s  failing.”  He 
conceded  that  there  “might”  be  a 
problem  with  the  memory  module, 
which  Memotech  replaced.  They  then 
sent  back  my  system. 

When  the  system  returned,  again  1 
could  make  the  32K  memory  work  by 
itself  only,  not  together  with  either  the 
Timex  printer  or  Memotech’s  keyboard. 
The  keyboard,  too,  only  worked  by 
itself.  The  store  from  which  I  bought 
the  memory  unit  was  kind  enough  to 
take  it  back  in  exchange  for  a  Timex 
16K  memory  (and  even  refunded  the 
difference  in  price!),  with  which  I 
have  had  no  problems.  I  sent  the  key¬ 
board  back  to  Memotech,  requesting 
a  refund,  citing  the  “free  ten-day  trial 
period  ”  clause  in  their  warranty,  stat¬ 
ing  that,  while  the  ten  days  had  elapsed 
all  the  problems  had  begun  the  instant 
I  began  using  the  keyboard  and  that  I 
had  been  in  contact  with  them  right 
from  the  start.  They  refused  to  give 
me  a  refund,  claiming  that  the  refund 
applied  only  to  those  who  had  pur¬ 
chased  directly  from  them,  but  instead 
returned  a  replacement  for  my  key¬ 
board.  If  I  wanted  a  refund,  they  told 
me,  I  would  have  to  get  it  where  I 
bought  the  keyboard. 

The  store,  of  course,  did  not  want 
to  give  me  a  refund,  because  the  1500 
would  soon  be  released  with  its  “real” 
keyboard,  and  auxiliary  keyboards  for 
Timex  computers  would  soon  be  obso¬ 
lete.  They  said  that  I  should  contact 
Memotech  for  a  refund.  (My  guess  is 
that  Memotech  is  stuck  with  a  ware¬ 
house  full  of  these  useless  keyboards.) 
As  I  expected,  the  replacement  worked 
no  better  than  the  original.  At  this 
point  I  no  longer  had  their  32K  mem¬ 
ory,  but  the  keyboard  worked  with 
neither  Timex’s  printer  nor  the  16K 
memory. 

By  this  time  I  had  heard  from  the 
South  Bay  Area  Timex/Sinclair  Users’ 
Group  (mentioned  in  my  October 
column)  that  Memotech  was  offering  a 
free  “modification”  to  purchasers  of 
their  32K  memories.  It  seems  several 
other  people  had  discovered  that  their 
memories  did  not  work  with  Timex 
printers.  Yet  all  the  time  I  had  been  in 


communication  with  Memotech  they 
insisted  there  was  no  incompatibility 
between  their  products  and  Timex 
printers;  furthermore,  they  had  never 
heard  of  anyone  having  any  problems 
like  mine.  Altogether,  I  went  through 
three  32K  memory  modules  and  two 
keyboards  without  finding  even  one  1 
could  use. 

Now  Dr.  Dobb’s  has  received  a 
press  pack  announcing  Memotech’s 
$595  MTX-512  World  Class  Comput¬ 
er!  M  jt  has  a  Z80A  4MHz  processor 
with  80K  standard  RAM  (expandable 
to  512K;  16K  is  dedicated  to  video). 
Among  other  things,  it  comes  with 
Oxford  BASIC  and  a  language  called 
NODDY,  a  real  time  clock,  and  a  79- 
key  keyboard.  I  hope  this  product  is 
better  than  the  peripherals  I  couldn’t 
use,  and  that  others  will  encounter 
more  competent  service  and  better 
support  and  attitude  than  I  did.  I 
know  I’ll  never  get  the  chance  to  find 
out.  Reader  Service  No.  119. 
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16-Bit  Software  Toolbox  (Column)  5,  58,  111,  214,  278, 
328,  400,  551,  618.  707 
6502,  Instructions  of  270 
6800,  Instructions  of  270 
68000 

Forth  and  the  Motorola  68000  495 
Forth  Assembler  502 
6809 

Cross  Assembler  272 
Threaded  Code  145 
8080 

to  Z80  Translator  198 
fig-Forth  Directory  and  File  System  180 
8088  Line  Generator  Subroutine  330 

ACTxx  Cross  Assemblers  478 

ADA  Subset  for  Micros  see  AUGUSTA 

AUGUSTA 

Part  I:  An  ADA  Subset  for  Micros  14 
Part  II:  P-Code  Interpreter  114 
Part  III:  Recursive  Descent  Compilers  231 
Part  IV:  The  AUGUSTA  Compiler  (Continued)  348 
Algorithms 

Binary  Magic  Numbers  176 

Fast  Circle  Routine  (IBM  PC/IBM  Pascal)  247 

Fast  Divisibility  287 

Simple  Graphics  for  Printer  (Pascal)  692 
Anatomy  of  a  Digital  Vector  and  Curve  Generator  380 
Apples,  Fast  Circles  for  723 
Assembler,  68000  Forth  502 
Assembly  Routine,  Integer  Square  Route  216 
Attaching  a  Winchester  Hard  Disk  to  the  S-100 
Bus  600 

B-Tree  ISAM  Concepts  289 
BASIC 

A  Common-Sense  Guide  to  Faster,  Smaller 
BASIC  147 

Program  Linkage,  Forth  to  BASIC  64 
Baden,  W.  692 
Barnhart,  J.  495 
Bartholomew,  A.  289 
BDOS 

Calls  for  C  293 
Function  Calls  318 
Bergman,  E.  E.  55 

Binary  Magic  Numbers:  Some  Applications  and 
Algorithms  176 
BIOS  Calls  for  C  293 
Blum,  R.  275,  334,  396,  470,  546,  627,  702 
Bolstad,  T.  293 

C  ( see  also  Small  C) 

C  Screen  Editor,  Enhancing  251 
CP/M  BDOS  and  BIOS  Calls  for  293 
RED:  A  Better  C  Screen  Editor  361,  446 
/UNIX  Programmer’s  Notebook  567,  720 
Comments  on  “Fifth  Generation  Computers"  151 
Common-Sense  Guide  to  Faster,  Smaller  BASIC  147 
Compilers 

AUGUSTA:  Recursive  Descent  Compilers  231 
Design  149 

Computers,  “Fifth  Generation”  151,  411 
Coroutines,  Program  Linkage,  Forth  to  BASIC  64 
Cortesi,  D.E.  30,  90,  212,  285,  392,  415,  492,  565, 

639,  719 

CP/M 

Application  Note  Fourteen  703 
CP/M  Exchange  (Column)  46,  72,  152,  167,  275,  334, 
396,  470,  546,  627,  702 
Linking  CP/M  Functions  to  Your  High-Level 
Program  70 

UNIX  to  CP/M  Floppy  Disk  File  Conversion  570 


Index 

Utilities 

BDOS  and  BIOS  Calls  for  C  293 
DIR.  ASM  72 
RECLAIM  170 

CP/M-80  Expansion  Card  for  the  Victor  9000  92 
CP/M  Plus 
BIOS  546 

Direct  Access  Disk  I/O  Benchmarks  415 
Cross  Assembler,  ACTxx  478 
Curve  Generator  and  Digital  Vector,  Anatomy  of  380 

Daetwyler,  D.  298 
Dates,  Julian  323 
DDA  Vector  Generator  380 
Deppe,  C.  298 
Dettmann,  T.R.  272 

Digital  Vector  and  Curve  Generator,  Anatomy  of  380 

Disassembler,  REVAS  95 

DML  Parser  662 

Dobb’s  Ex  Machina  57 

Doherty,  M.J.  151 

Dr.  Dobb’s  Clinic  (Column)  90,  212,  285,  392,  415,  492. 
565,  639,  719 

Dumb  Terminals,  Cursor  Control  733 

Duncan,  R.  4,  58,  111,  214,  278,  328,  400,  551,  618 

Editorials  4,  52,  165,  227,  345,  413,  489,  564,  638,  717 
Enhancing  the  C  Screen  Editor  251 
Enright,  M.T.  725 

Epson,  Using  the  Bit  Plot  Graphics  608 

Fast  Divisibility  Algorithms  287 
Fast  Matrix  Operations  in  Forth  383,  433 
Faster  Circles  for  Apples  723 
Favitta,  M.  218 

Fifth  Generation  Computers  151,  411 
Forth 

68000  Forth  Assembler  502 

8080  fig-Forth  Directory  and  File  System  184 

and  the  Motorola  68000  495 

Coding  Standards  538 

Fast  Matrix  Operations  315,  383,  433 

Game  of  GO  516 

Nondeterministic  Control  Words  510 
Precompiled  Modules  529 
Program  Linkage  to  BASIC  64 
Say"  Forth  Votrax  Driver”  194 
Series  Expansion  311 
Sort  542 
Syntax  668 

Forth-83  and  Vocabularies  535 
A  Fundamental  Mistake  in  Compiler  Design  149 
Freed,  E.E.  176 

The  Game  of  Life  on  the  IBM  PC  304 

Garfinkel,  S.L.  304 

Gates,  W.C.  311 

Gay,  D.  608 

Glass,  H.  688 

Goldman,  O.  600 

Goodman,  R.  268 

Gordon,  H.T.  145,  287 

Graphics 

Faster  Circles  for  Apples  723 
Printing  Graphics  Using  the  IBM  PC  298 
Simple  Graphics  for  Printer  692 
Using  the  Epson  Bit  Plot  Graphics  608 
Gregory,  R.  21 
Grigonis,  R.  441 

Harrison,  H.  4,  24,  57,  92 

Hardware  Reviews  see  Reviews,  Hardware 

Harry,  D.  662 


Head,  G.  46,  72,  152,  167 
Howard,  A.D.  251 
Hunt,  D.S.  29 

IBM  PC 

The  Game  of  Life  on  304 
Printing  Graphics  with  298 
Sizing  Memory  on  401 
Integer 
Division  533 
Square  Root  216 
Irving,  R.  147 

ISAM,  B-Tree  Concepts  289 

Jolly,  G.W.  273,  480 

Jones.  D-W.  318 

JRT  Pascal:  Another  Look  29 

Julian  Dates  for  Microcomputers  323 

Kernel  for  the  MC  68000  646 
King,  G.  323 

Lee,  D.L.  247 

Linking  CP/M  Functions  to  Your  High-Level  Program  70 
Lyons.  V.  97 

Magic  Wand  Utility  393 
Manning.  M.  542 

Matrix  Operations  in  Forth  315,  383,  433 
MC  68000.  Kernel  for  646 
McCabe,  C.K.  194 
McKeon,  B.  126 

McWORDER:  A  Tiny  Text  Editor  428 

McWorter.  W.A.  428,  733 

Mitchell,  E.  14,  114,  348 

Monroe,  A.J.  184 

Moran,  J.  700 

Morgenstern,  L.  64 

Motorola  68000,  Forth  and  495 

Murphy.  W.V.  170 

Newberry,  S.  478 

Nondeterministic  Control  Words  in  Forth  510 
Odette.  L.L.  510 

Of  Interest  (Column)  47,  99,  159,  221,  280,  336,  406, 

483,  557,  631,  712 

P-Code  Interpreter  114 
Parser,  DML  662 
Pascal.  JRT  29 
Passe.  S.  646 
Perry,  M.A.  502 

PISTOL:  A  Forth-Like  Portably  Implemented  STack 
Oriented  Language  55 
Precompiled  Forth  Modules  529 
Printer.  Simple  Graphics  for  692 
Program  Linkage  by  Coroutines:  Forth  to  BASIC  64 
Pulier,  M.L.  723 

Radio  Shack  TRS-80  see  TRS-80 
Ream,  E.K.  361,  446 

RECLAIM:  A  File  Reclamation  Utility  for  Destroyed 
Directories  170 

Recursive  Descent  Compilers  231 
RED:  A  Better  C  Screen  Editor  361,  446 
REVAS  Disassembler  95 
Reviews,  Book  96,  273,  480,  700 
Review,  Hardware 

CP/M-80  Expansion  Card  for  the  Victor  9000  92 
Reviews,  Software 
ACTxx  Cross  Assemblers  478 
JRT  Pascal  29 
REVAS  Disassembler  95 


Unica  and  XM-80  218 

ZAS  Z8000  Software  Development  Package  272 
Rothstein,  J.B.  96,  700 
Ruzinsky,  S.A.  315,  383,  433 

S-100  Bus,  Attaching  a  Winchester  to  600 
Say“  Forth  Votrax  Driver"  194 
SBC,  TSX  and  TXS:  Instructions  of  the  6800 
and  6502  270 
Scarpelli,  A.T.  198 
Screen  Editors 
Enhancements  251 

RED:  A  Better  C  Screen  Editor  361,  446 
SEND  and  RCV,  a  Forth  Implementation  of  the 
XMODEM  Protocol  523 
Serial  to  Parallel:  A  Flexible  Utility  Box  422 
Series  Expansion  in  Forth  311 
Shaw,  G.W.  II  535 
Shiftman,  R.  380 

Shifts  and  Rotations  on  the  Z80  268 
Signed  Integer  Division  533 
Skjellum,  A.  567,  720 
Small-C 

Compiler,  V.2  31 
Help  Facility  583 
Operating  System  126 
Smith,  R.L.  533 

Software  Reviews  see  Reviews,  Software 
Solntseff,  N.  529 

Some  Forth  Coding  Standards  538 
Staneff,  J.  583 
Stetson,  E.B.  273 

Stone  Age  Computers:  6,000  Years  of  Computing 
Science  36 

TRS-80  8080  to  Z80  Translator  198 
Tan,  B.T.G.  270 
Taylor,  D.  216 
Taylor,  R.  523 

Text  Editor,  McWORDER  428 

Towards  a  More  Writeable  Forth  Syntax  688 

Trace  Function,  DDT  318 

Translator,  TRS-80  8080  to  Z80  198 

Unica  218 
UNIX 

C/UNIX  Programmer’s  Notebook  567,  720 
to  CP/M  Floppy  Disk  File  Conversion  570 
Using  the  Epson  Bit  Plot  Graphics  608 

Victor  9000,  CP/M  Expansion  Card  92 

Watson,  T.  98 
Weiger,  W.  70 

When  a  Page  Is  Not  a  Page:  Forth-83  and 
Vocabularies  535 

Wiesenberg,  M.  44,  99,  159,  221,  280,  336,  406,  483, 

557,  712 

Wiggins,  R.  53,  165,  227,  345,  413,  489,  564,  638,  717 
Wilcox,  A.D.  422 
Willoughby,  S.  95 
Wilson,  W.E.  570 

Winchester  Hard  Disk,  Attaching  to  the  S-100  Bus  600 
Wischmeyer,  E.  538 

XM-80  and  Unica  218 

XANADU:  Hypertext  from  the  Future  21 

XMODEM  Protocol,  Forth  Implementation  523 

Yes,  You  Can  Trace  Through  BDOS  318 

Z80 

8080  to  Z80  Translator  198 
Shifts  and  Rotations  268 
ZAS  Z8000  Software  Development  Package  272 


The  Dr.  Dobb's  Series 

" There's  more  creativity,  wild  ideas,  and  raw  enthusiasm  here 
per  page  than  you  are  likely  to  find  anywhere  else  in  the 
personal  computing  press. " 

Creative  Computing 


Volume  1 

Chronicles  the  advent  of  the  microcomputer  era  in  1976.  Always  pertinent  for  bit 
crunching  and  byte  saving,  home-brew  computer  projects,  and  the  technical 
history  of  home  computing.  Topics  include:  Tiny  BASIC,  the  first  words  on  CP/M, 
Speech  Synthesis,  Floating  Point  Routines,  6502  Disassembler  for  the  Apple,  and 
much  more. 


Volume  2 

The  small  computer  emerges  as  a  powerful  tool  for  the  modern  age  in  these  issues 
from  1977.  Topics  include:  Lawrence  Livermore  Lab's  BASIC,  Dr.  Starkweather's  PILOT, 
Using  a  Modem,  String  Handling  Techniques,  Ciphers,  Turtle  Graphics,  micro  utilities. 

Volume  3 

Explores  the  foundations  of  the  mass  market  computer  industry  in  1978.  Topics 
include:  Programming  in  BASIC,  PILOT,  and  Pascal,  RAM  Memory  Testers,  Apple  utility 
programs,  S-100  Bus  Standard,  STRUBAL:  A  Structured  BASIC  Compiler. 

Volume  4 

Heralds  the  widespread  acceptance  of  the  microcomputer  in  America.  Innovative 
ideas  and  articles  guide  the  reader  through  the  age  of  discovery  in  1979.  Topics 
include:  Selecting  Business  Software,  Microcomputer  Speech  and  Music,  Informa¬ 
tion  Networks,  interfacing  techniques. 

Volume  5 

Focuses  on  the  technological  promise  of  the  modern  microcomputer  and  the 
creative  challenge  facing  programmers  in  1980.  Topics  include:  The  revolutionary 
impact  of  CP/M,  C  programming  and  the  UNIX  operating  system,  survey  of  com¬ 
puter  networks,  software  portability,  introduction  to  FORTH,  compiler  writing. 

Volume  6 

The  microcomputer  enters  the  mainstream — these  issues  assess  the  revolutionary 
impact  of  microcomputers  on  the  individual  and  on  our  society  in  1981.  Topics 
include:  Computer  Conferencing,  The  Power  of  FORTH,  8-  and  16-Bit  Technology, 
Rubik's  Cube  Simulator,  An  Adventure  Game  Development  System. 

Volume  7 

Examines  the  potential  of  powerful  16-bit  micros  including  the  birth  of  the  IBM  PC 
in  1982.  Topics  include:  In-depth  coverage  of  FORTH,  68000, 8088  programming,  C 
software  tools,  utilities  for  CP/M  including  a  spelling  checker,  using  bulletin  boards, 
and  more. 

Volume  8 

DDJ  turns  pro.  Some  of  the  most  powerful,  professional  programmer's  tools  ever 
published  in  a  magazine  are  in  this  volume.  Jim  Hendrix's  Small  C  compiler.  Ed 
Ream's  RED  screen  editor.  A  microcomputer  subset  of  the  Defense  Department's 
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